Running Finder

An open-source platform connecting runners with local running clubs
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
3. ER Model
4. Roadmap
5. Static Code Analysis
6. Contributing
7. License
8. Contact
9. Acknowledgments

🚀 About The Project

Running Finder is a platform that helps runners discover and connect with running clubs and events in their area. The application displays running clubs and events on an interactive map, allowing users to filter by preferences like distance, weekday, or difficulty.

Key Features

• Interactive Map: View running clubs and events plotted on Google Maps
• Advanced Filtering: Find runs by distance, weekday, and difficulty level
• Club Discovery: Browse and join local running clubs
• Event Registration: Register for upcoming runs directly through the platform
• Authentication: Sign in with GitHub or email to save preferences and manage registrations

Built With

• Next.js - React framework with server-side rendering
• React - Frontend library for building user interfaces
• Drizzle ORM - TypeScript ORM for SQL databases
• TailwindCSS - Utility-first CSS framework
• Neon - Serverless Postgres database
• Shadcn UI - Reusable component library
• Jest & Playwright for testing

🚦 Getting Started

Prerequisites

• Node.js (v18 or higher)
• pnpm

  npm install -g pnpm

• Postgres database (or use the provided Docker setup)

Installation

1. Clone the repository

   git clone https://github.com/Joelheile/RunningFinder.git
   cd RunningFinder

2. Install dependencies

   pnpm install

3. Create a .env.local file based on .env.example and add your API keys

   cp .env.example .env.local

4. Set up the database

   # For development with Docker
   sh docker_run.sh
   
   # Generate database schema
   pnpm dev:generate
   pnpm dev:push
   
   # Seed the database (optional)
   pnpm dev:seed

5. Start the development server

   pnpm dev

6. Access the API documentation at http://localhost:3000/docs

🗂️ Project Structure

runningfinder/
├── src/                   # Source code
│   ├── app/               # Next.js app router pages
│   ├── components/        # React components
│   ├── lib/               # Utilities, hooks, and business logic
│   │   ├── authentication/# Auth configuration
│   │   ├── db/            # Database schema and connections
│   │   └── types/         # TypeScript type definitions
├── public/                # Static assets
├── tests/                 # Test files
├── drizzle/               # Database migrations
└── playwright-tests/      # End-to-end tests

🧪 Testing

Run all tests with:

pnpm tests

Or run specific test suites:

# Unit tests
pnpm jest unit

# Integration tests
pnpm jest integration

# End-to-end tests
npx playwright test

🛣️ Roadmap

• Combine Google Maps marker dragging and place search
• Enhance club dashboard with role-based permissions
  • Page editing
  • Membership management
  • Registration management
• Support for additional sport types
• Weather API integration for run forecasts
• Strava API integration for syncing runs

See the open issues for a full list of proposed features and known issues.

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Don't forget to check our Contributing Guidelines.

📄 License

Distributed under the MIT License. See LICENSE for more information.

📞 Contact

Project Link: https://github.com/Joelheile/RunningFinder

Acknowledgments

• Google Maps Platform for mapping services
• Auth.js for authentication
• All the amazing runners and clubs who inspired this project!

(back to top)

Use cases

• Runs
  • are displayed on interactive map
  • users can register for runs
  • runs can be filtered by distance, weekday and difficulty
• Clubs
  • Dashboard: Get to know knew running clubs
  • Members: Join and leave clubs, view club details and runs
  • Admins: Add and manage club details and runs

Data Generation

The data in the database is user generated and not generated by the backend. For the first batch of data I used a custom scraper to scrape the data from a competitor. This way first users were more motivated to use the plattform and suggest own runs.

Roadmap

• Setup database & API routes
• Add club
• Add recurring runs (on weekly basis)
• Authentication (when adding a run or club, you'll be redirected to /api/auth/signin)
• Displaying runs a user has liked on a own page
• Combine Google Maps marker dragging and place search
• Enhance club dashboard using roles
  • Page editing
  • Membership management
  • Registration management
• Open plattform for other sport types
• Implement weather API to forecast conditions for runs
• Implement Strava API to sync runs

(back to top)

Architecture

flowchart TD
    %% Main Nodes
    Users(["👥 Users"]):::users --> AppRouting{{"🔀 App Routing"}}:::routing

    %% Application Modules in a row
    AppRouting --> RunsModule & ClubsModule & MapModule

    subgraph ApplicationModules["Application Modules"]
        direction LR
        RunsModule["🏃 Runs Module"]:::module
        ClubsModule["👥 Clubs Module"]:::module
        MapModule["🗺️ Map Module"]:::module
    end

    %% Application Layer below modules
    RunsModule & ClubsModule & MapModule --> ApplicationLayer
    ApplicationLayer["⚙️ Application Layer"]:::appLayer

    %% API Gateway and Database
    ApplicationLayer <--> APIGateway
    APIGateway["🔌 API Gateway"]:::apiGateway
    APIGateway <--> Database
    Database[("💾 Database")]:::database

    %% Advanced styling
    classDef users fill:#FF6B6B,stroke:#333,stroke-width:2px,color:white,font-weight:bold,border-radius:8px
    classDef routing fill:#4ECDC4,stroke:#333,stroke-width:2px,color:white,font-weight:bold
    classDef module fill:#48BFE3,stroke:#333,stroke-width:2px,color:white,font-weight:bold,border-radius:4px
    classDef appLayer fill:#56CFE1,stroke:#333,stroke-width:2px,color:white,font-weight:bold,border-radius:4px
    classDef apiGateway fill:#5E60CE,stroke:#333,stroke-width:2px,color:white,font-weight:bold,border-radius:4px
    classDef database fill:#7400B8,stroke:#333,stroke-width:2px,color:white,font-weight:bold

    %% Apply classes
    class Users users
    class AppRouting routing
    class RunsModule,ClubsModule,MapModule module
    class ApplicationLayer appLayer
    class APIGateway apiGateway
    class Database database

    %% Style the Application Modules subgraph
    style ApplicationModules fill:#FFFDD0,stroke:#CBD5E0,stroke-width:2px,color:#2D3748,font-weight:bold

Loading

Static Code Analysis

I use ESLint for static code analysis. Mostly running it before pulling my branch, it has helped me to catch bugs and errors before they get merged into the main branch. It is also a great tool to stay consistent. For example having a consistent Image tag and not switching.

You can run it using:

pnpm run lint

I hope you liked the project :)