JPM

JPM is a monorepo with a modern web application, a FastAPI service, and PostgreSQL for local development. The existing proof of concept remains in legacy/aircraft-manager.

Structure

• apps/web — Next.js, React, TypeScript, and Tailwind CSS frontend
• services/api — FastAPI application with a PostgreSQL-ready SQLAlchemy setup
• compose.yaml — local web, API, and PostgreSQL stack
• legacy/aircraft-manager — original POC, preserved as-is

Local development

1. Copy .env.example to .env and replace the development password if needed.
2. Start the stack with npm run dev (or docker compose up --build).
3. Open the web app at http://localhost:3000, API docs at http://localhost:8000/docs, and the health endpoint at http://localhost:8000/api/v1/health.

Source directories are bind-mounted in Compose, so edits to the frontend and API reload automatically. PostgreSQL data is stored in the named postgres_data volume.

VS Code Dev Container

Install the Dev Containers extension, open this repository in VS Code, and run Dev Containers: Reopen in Container. The container starts PostgreSQL and provides Node.js 24, Python 3.12, Docker/Compose, GitHub CLI, Codex CLI, and PostgreSQL client tools. It installs the frontend and API dependencies once the workspace is created.

Run the application processes directly from the integrated terminal:

npm run web:dev
services/api/.venv/bin/uvicorn --app-dir services/api app.main:app --reload

VS Code forwards ports 3000, 8000, and 5432. The Docker CLI is also available for inspecting or managing the local development containers.

The Dev Container bind-mounts the host ~/.codex directory at the container user's ~/.codex, so Codex uses the same account, settings, skills, and session history. The mount is intentionally read/write to let Codex continue sessions; only use this Dev Container with a workspace you trust.

Running services without Docker

Frontend:

cd apps/web
npm install
npm run dev

API (Python 3.12 recommended):

cd services/api
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/uvicorn app.main:app --reload