This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass.
What I Built
Sometimes the hardest part of going for a ride happens before you even get on the bike.
Where should you go? Is there anyone nearby who wants to join? Will their idea of an “easy ride” leave you struggling to keep up?
I built RideCircle to help answer those questions.
It’s a cycling discovery app where you can find nearby riders with compatible preferences, explore destinations and routes, and organize group rides. I started with Chennai, using real destinations such as Marina Beach and Semmozhi Poonga.
You can set your pace, experience level, preferred ride distance, availability, and interests. RideCircle uses those preferences to help you find people you could comfortably ride with—and explains why a match appears.
You can also:
- Explore the map: browse destinations, cyclists, routes, and events.
- Search your area: find results within the map area you’re viewing.
- Organize a ride: choose a meeting point and set a participant limit.
- Join a group: mark yourself interested or attending, and see who’s coming.
- Control your visibility: keep your profile private until you choose to make it discoverable.
The app is for someone who wants company on a weekend ride, a beginner looking for a relaxed group, or a cyclist who wants somewhere different to explore.
Cycling apps already exist. My focus here is the decision before the ride: finding a place, a compatible person, and a time that works.
The goal is to make planning short enough that you actually leave the house.
Screenshots
RideCircle currently runs locally with Docker.
The main flow takes you through creating a profile, exploring the map, finding compatible cyclists, and organizing a group ride.
The demo includes clearly labeled fictional riders and sample events so the discovery experience can be explored without needing an existing community. The destinations are real, and the bundled cycling route includes its data source.
To run it yourself, follow the environment setup in the repository README, then run:
docker compose up -d --build
Open http://localhost:5173.
The README also includes instructions for enabling local Gemma inference.
Code
The source code is available on GitHub:
RideCircle
A local MVP for finding compatible cyclists, exploring real destinations, and organizing group rides. React + TypeScript, FastAPI, PostgreSQL/PostGIS, and optional local Gemma inference through Ollama.
Start the app
Install Docker Desktop with its Linux engine enabled. From this directory:
Copy-Item .env.example .env
# Replace JWT_SECRET with a random secret of at least 32 characters.
docker compose up -d --build
Open http://localhost:5173. Create your own account, set your preferences, then explore. API documentation: http://localhost:8011/docs. PostGIS is bound to localhost port 54329. Services are local only. To stop them, run docker compose down; the database volume survives. Do not use down -v unless you intend to erase your local database.
The seed contains three sourced Chennai destinations, a real provider-calculated “Garden to coast” bicycle route, four explicitly fictional sample cyclists, and four sample events. Sample people and events are labeled and can be hidden…
Explore the RideCircle repository →
The project contains the frontend, backend, database migrations, seed data, tests, and Docker configuration.
I’ve documented the local setup, where the map and route data come from, and the parts that are still outside the scope of this prototype.
How I Built It
RideCircle uses:
| Technology | Its role |
|---|---|
| React + TypeScript | Application interface |
| Leaflet | Interactive map |
| FastAPI | Backend API |
| PostgreSQL + PostGIS | Data storage and geographic searches |
| Gemma 3 through Ollama | Local AI search integration |
| Docker Compose | Local application setup |
Turning a request into search preferences
The AI integration addresses a small but useful problem: turning a cycling request into search preferences.
For example:
“Find beginner cyclists who enjoy relaxed rides on Sunday mornings.”
The Gemma integration asks the model to return structured preferences, such as experience level, pace, day, and time. The backend validates that output before using it to search the database.
The model’s job stops at interpreting the request. Location filtering, compatibility checks, privacy rules, and event capacity are handled by the application.
That boundary matters. An invented cyclist or destination would make the app frustrating to use. Search results need to come from records that actually exist.
Keeping keyword mode transparent
The project also includes a clearly labeled keyword mode for running the app before downloading a model. That is the mode used in the current local deployment.
It recognizes explicit terms such as “beginner,” “Sunday,” and “relaxed,” but has more limited interpretation than the Gemma integration.
Grounding the map in real data
For the map, I used OpenStreetMap data and source-backed destinations. Route geometry comes from a bicycle routing provider rather than being generated by the language model.
Privacy also shaped the implementation. Public cyclist results omit email addresses and exact stored coordinates. Rider markers use broad neighborhood reference points, while event meeting points are public locations chosen by organizers.
Why Does Open Innovation Matter?
For RideCircle, open innovation makes the project easier to run, inspect, and change.
With Gemma running through Ollama, search interpretation can happen on the user’s machine without sending the search text to a hosted model API. That also gives me room to experiment with prompts and model sizes without paying for every inference request.
It doesn’t make the whole application offline. Map tiles and live route calculations still need internet access. But it gives me control over where the AI part runs.
The open tools around the model matter just as much. PostGIS handles geographic searches, Leaflet makes the map interactive, and OpenStreetMap provides the map data. Together, they let me build a useful local prototype without a paid mapping subscription.
A closed API could also interpret cycling requests. What this approach gives me is the ability to run that part locally, inspect the surrounding code, and adapt it as the project develops.
That feels especially relevant for a community app. Someone should be able to take the project, add destinations in their own city, adjust the matching rules, and build something that fits their local cycling community.
What comes next?
RideCircle is still an MVP. It hasn’t yet been validated through an actual group ride, and the sample profiles aren’t evidence of an active community.
The next useful test is getting a few real cyclists to try it and seeing whether it helps them arrange a ride.
That’s the outcome I care about: a plan that turns into people getting on their bikes.
Top comments (0)