Code / flights-turbo
flights-turbo
TypeScript · 176 files · main @ c0e5331
Files
- .agents/skills/flights-turbo/
- .claude/
- .codex/
- apps/
- .eslintrc.js
- .gitignore
- .nvmrc
- .yarnrc.yml
- DB_PLAN.md
- package.json
- README.md
- tsconfig.base.json
- turbo.json
README
Flights Turbo
Turborepo playground for learning PostgreSQL query design, optimization, execution plans, indexing, pagination strategies, and API performance against the Postgres Pro Airlines demo database.
Stack
- Yarn 4 workspaces
- Turborepo
- NestJS REST API
- Raw
pgqueries, no ORM - Next.js App Router
- Read-only PostgreSQL pool
- Nest OpenAPI generation + Scalar API reference
- Local request telemetry with 7-day retention
Structure
flights-turbo/
├── apps/
│ ├── api/
│ │ └── src/
│ │ ├── airports/
│ │ ├── routes/
│ │ ├── database/
│ │ │ └── models.ts
│ │ └── gateway/
│ └── web/
│ ├── app/routes/
│ └── app/monitor/
├── package.json
├── turbo.json
└── .yarnrc.yml
Setup
nvm use
corepack enable
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.local.example apps/web/.env.local
yarn install
yarn dev
Local services:
- Next.js: http://localhost:3000
- REST API: http://localhost:4001/api
- Scalar API docs: http://localhost:4001/docs
- Gateway metrics API: http://localhost:4001/api/gateway/metrics
- Performance dashboard: http://localhost:3000/monitor
Starter endpoints
GET /api/airports?page=1&size=20&search=moscow
GET /api/routes?page=1&size=50&departureAirport=DME&arrivalAirport=LED
GET /api/gateway/metrics
SQL philosophy
The application intentionally avoids an ORM. Database shapes are represented as TypeScript types in apps/api/src/database/models.ts, while services contain parameterized SQL directly through pg.
The starter pagination queries use size + 1 instead of an additional COUNT(*) query to determine hasMore. This keeps the baseline inexpensive and leaves room to deliberately compare alternate pagination and counting strategies later.
Gateway telemetry
A global Nest interceptor records completed REST requests with:
- timestamp
- HTTP method
- normalized path
- status code
- request duration
Logs are stored locally as one NDJSON file per day under:
apps/api/.data/gateway/
Files older than 7 days are automatically removed. The gateway metrics endpoint calculates overall and per-endpoint request counts, error rates, average latency, p50, p95, and p99 from retained data.
The /api/gateway/metrics and /docs routes are excluded from telemetry so observing the API does not distort the measurements.
Useful commands
yarn dev
yarn dev:api
yarn dev:web
yarn build
yarn typecheck