A modern cycle-tracking app: sign in with Google, set your cycle length, log period days, add a profile picture, and see phase-based suggestions on the main calendar. Built with React/Vite/Tailwind (frontend), FastAPI (backend), PostgreSQL, and Redis, orchestrated with Docker Compose.
Recorded from the running app. Full-quality MP4 · still of the welcome screen
-
Google OAuth Create an OAuth 2.0 Client in Google Cloud Console and set Authorized redirect URI to
http://localhost:8000/auth/callback. See docs/02-google-oauth-setup.md. -
Environment Copy
.env.exampleto.envin the project root and setGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET. -
Run
docker compose up --build
Frontend: http://localhost:5173 · Backend: http://localhost:8000 (Postgres + Redis start with them). Open the frontend URL, sign in with Google → Onboarding (cycle length + last cycle) → Track / Insights / Friends tabs.
- frontend/ — React + Vite + Tailwind. Screens (Welcome, Onboarding, LastCycle, and the AppShell tabs Track / Insights / Friends),
src/api/client,src/cycle/phase engine,src/context/authContext.jsfor the signed-in user. - backend/ — FastAPI as the
apppackage (app.main:app): OAuth, Redis sessions, PostgreSQL, and the users / follows / content / health routers. - backend/migrations/ — Alembic migrations. They are the only thing that changes the schema.
- shared/phase-cases.json — Golden cases for the cycle phase engine. The backend and frontend implement the same rules separately and both test suites assert against this file, so the two cannot drift apart.
- docs/ — Educational docs (overview, Google OAuth, OAuth/sessions, database/onboarding, Docker/CI, pre-commit, cycle phases, circle follows).
- docker-compose.yml — frontend (Vite dev server), backend, postgres, redis.
- Full stack in Docker:
docker compose up --build— frontend on 5173, backend on 8000. Frontend source is mounted so edits trigger Vite HMR. The backend container applies migrations before it starts serving. - Frontend only locally:
cd frontend && npm install && npm run dev(talks to backend athttp://localhost:8000). - Backend only locally:
cd backend pip install -r requirements-dev.txt export DATABASE_URL=... REDIS_URL=... GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... alembic upgrade head # never create_all: migrations own the schema uvicorn app.main:app --reload
- Tests:
cd backend && pytestandcd frontend && npm test. - Migrations:
alembic revision -m "..."to add one,alembic upgrade headto apply,alembic checkto confirm the models and the schema still agree. - Pre-commit:
pip install pre-commit && pre-commit install. - CI: GitHub Actions on push/PR to
main— frontend lint/test/build, backend lint, migration round-trip,alembic check, and pytest, plus a Docker image build.
The schema predates Alembic. A database created before migrations existed needs to be told where it already is, once:
cd backend
alembic stamp 0001_initial # "this DB already has the original schema"
alembic upgrade headA fresh database just runs alembic upgrade head.
Set through the environment (see .env.example):
| Variable | Default | Notes |
|---|---|---|
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
— | Required for sign-in. |
DATABASE_URL |
local Postgres | |
REDIS_URL |
local Redis | Sessions and rate limiting. |
FRONTEND_ORIGIN |
http://localhost:5173 |
CORS origin and post-login redirect target. |
BACKEND_PUBLIC_URL |
http://localhost:8000 |
Used to build the OAuth redirect URI. |
COOKIE_SECURE |
false |
Set to true anywhere served over HTTPS, so the session cookie is not sent in the clear. |
LOG_LEVEL |
INFO |
|
SESSION_TTL_DAYS |
7 |
|
AVATAR_MAX_UPLOAD_BYTES |
5242880 |
Largest profile picture accepted, before it is re-encoded. |
GET /health— liveness. Touches no dependency; answers as long as the process is up.GET /health/ready— readiness. Returns 503 unless both Postgres and Redis answer. This is what Compose waits on.
All in docs/:
- 01-overview-and-setup.md — What the app does, stack, layout, how to run.
- 02-google-oauth-setup.md — Create Google OAuth client and redirect URI.
- 03-oauth-and-sessions.md — OAuth flow and Redis sessions.
- 04-database-and-onboarding.md — PostgreSQL schema and onboarding API.
- 05-docker-and-ci.md — Docker Compose and GitHub Actions CI.
- 06-pre-commit.md — Pre-commit hooks and usage.
- 07-cycle-phases.md — Four cycle phases and the dashboard under the calendar.
- 08-circle-follows.md — Nickname search, friend vs partner follows, privacy.
- 09-profile-pictures.md — Avatar upload, normalization, and who can see it.
- Night Bordeaux
#461220 - Burnt Rose
#8c2f39 - Dusty Mauve
#b23a48 - Powder Blush
#fcb9b2 - Peach Fuzz
#fed0bb
Private / unlicensed unless you add one.