Skip to content

Adding a New App

⚠️ Stub. This guide will be expanded once template-app/ and the scaffold script are built (see PLAN.md milestones 3 and 4).

TL;DR

make new-app NAME="Invoice Tracker" SLUG=invoice-tracker KIND=product

This copies template-app/ into apps/products/invoice-tracker/, replaces placeholders, allocates ports, generates a Postgres database name, registers the app in the root compose file, boots it, and runs the smoke test.

When the script finishes, you have a running app. Customise the data model, routes, and UI to fit your use case.

What the script does

See docs/content/adr/0004-template-app-pattern.md for the full list.

What you customise after scaffolding

  1. The data model in backend/src/models.py.
  2. Generate an Alembic migration: alembic revision --autogenerate -m "initial".
  3. CRUD routes in backend/src/routes/.
  4. The UI in frontend/src/pages/Home.tsx.
  5. The description and icon in app.manifest.yml.

What you don't change

  • The auth integration. It's already wired up via auth-client-py and auth-client-ts.
  • The Dockerfiles. The template's are correct.
  • The smoke test. It's inherited from the template and should keep passing.
  • The stack — see adr/0002-locked-stack.md.

Asking an AI agent to do it

See creating-an-app-with-ai.md.