TimeCalendar

Development setup

Docker

To start working on TimeCalendar, you must first install Docker.

Once Docker is installed, start the dev-env services (Postgres, Redis, and an nginx TLS proxy) in the background from the repository root:

bin/server-compose.sh up -d

The wrapper keeps the main checkout's historical server Compose project and gives each worktree its own project, network, containers, and named volumes. The default URLs remain https://api.timecalendar.host:1443, Postgres on localhost:37291, Redis on 127.0.0.1:37292, and the separately started NestJS server on http://localhost:3005. The self-signed TLS certificate the proxy serves is generated on first use and is not committed — see the dev TLS certificate.

Choose unoccupied host ports for another worktree with shell-scoped overrides:

TIMECALENDAR_TLS_PORT=24443 TIMECALENDAR_POSTGRES_PORT=47291 \
  TIMECALENDAR_REDIS_PORT=47292 bin/server-compose.sh up -d

Generation and server tests do not need nginx. Start only their dependencies:

bin/server-compose.sh up -d postgres redis

With alternate ports, pass the same ports to the test-profile server command:

TIMECALENDAR_POSTGRES_PORT=47291 TIMECALENDAR_REDIS_PORT=47292 \
  bin/server-compose.sh up -d postgres redis
cd server
DATABASE_URL=postgres://postgres@localhost:47291/timecalendar_test \
  REDIS_URL=redis://127.0.0.1:47292 npm run generate:openapi

Node.js

TimeCalendar is written in TypeScript and runs with Node.js. Install Node.js on your environment.

Once Node.js is installed, install npm dependencies:

npm install

Init your environment

Copy the file server/.env.sample to a new file named server/.env. In development most values already have sensible defaults (see server/src/config/environments/development.ts), so this file only needs NODE_ENV=development.

Working in a git worktree

A git worktree only checks out tracked files, so the gitignored files a working checkout needs — server/.env, web/.env.local, the Firebase key, the generated husky helper .husky/_/, and node_modules — are all absent in a fresh worktree (no pre-commit hook runs there at all, silently). Run this first in every new worktree to symlink the shared secrets from your main checkout and install dependencies:

npm run setup:worktree

It is idempotent and a no-op in the main checkout.

Firebase

TimeCalendar uses Firebase to send push notifications and save application settings. You can either use the private development Firebase account or create your own.

Create your own service account key

On the Firebase Console, create your own application. Go into your Project settings > Your apps and create a web application. Then, go in the Service accounts tab, and click on "Generate new private key", it will download a file. Copy it into server/config/serviceAccountKey.json.

You also need to create a Firestore Database. In the left bar, click on Firestore Database, then on "Create database". Select "Start in test mode", then "Next". Select any region for the Firestore location (you can select the nearest, eur3), then click on "Enable".

Start the server

To start the server, run the following command:

cd server && npm run dev

Mobile app

The React Native (Expo) app lives in mobile/ — see the mobile README for the toolchain (Node 24, JDK 17, Android SDK, Xcode), the dev-client build, and how to point a physical device at the server started above on :3005. It is a standalone npm project with its own npm install; the Architecture Book is at docs/mobile/architecture-book/.

The legacy Flutter app lives in app/. To run it against this local dev env (e.g. on an iOS simulator), first run npm run setup to wire up the /etc/hosts entries, web/.env.local, and the simulator's trusted dev cert (the cert step is macOS-only; the hosts step needs sudo — a physical Android device needs neither, it reaches the server over adb reverse), then follow the app README.

Tests

To run tests:

npm run test

Migrations

Run all commands in the server folder.

Migrations do not run automatically in development (RUN_MIGRATIONS=false), so run them manually after starting the Docker stack and before starting the server.

Create a migration

npm run db:generate

Run migrations

npm run db:migrate

Seed data

The dev database starts empty (the schools list is empty until seeded). Load the fixture data (schools, school groups) from the server folder:

npm run db:seed

Use npm run db:init to drop the database, re-run migrations, and reseed from scratch.