16 August 2026The system as it stood at the end of this day.
The system runs as 2 services: BackendBackend The main application: it runs the API and serves the website. and ProxyProxy The front door for web traffic: it receives requests from the internet and passes each one to the right service; it runs Traefik., with the database behind them. People use it through the website, which talks to an APIAPI The set of requests other software, including the website, can send to the application to read or change data. of 23 operations in 5 groups. Alongside them, AdminerAdminer Adminer, a web page for browsing and editing the database directly. also runs in production as an admin tool.
In production, the system runs in 2 places, both deployed automatically: Docker ComposeDocker Compose Docker Compose, a tool that starts a set of services together on one server; here it runs the system on a server the team manages itself. (Backend and Proxy) and FastAPI CloudFastAPI Cloud A hosting service that runs FastAPI applications. (Backend). Each place needs its own settings and secrets.
Exhibit 1How the parts fit together
Source: deployment files, CI workflows and code at commit 75b4026. An arrow points from a part to what it calls, routes to or relies on; dotted arrows exist only on engineers' machines.
Exhibit 2What callers can do with each part of the API, and who may
| Part of the API | What it lets callers do | Who can use it |
|---|---|---|
| Items APIItems API The part of the API for items: 5 operations (5 for signed-in users). | delete an item; list items; view an item; create an item; update an item | signed-in users: 5Signed-in users: delete an item; list items; view an item; create an item; update an item. |
| Sign-in APISign-in API The part of the API for sign-in: 5 operations (3 open to anyone, 1 for signed-in users, 1 for administrators only). | sign in and get an access token; check that an access token is valid; preview the password-reset email; start a password reset by email; set a new password after a reset | anyone: 3, signed-in users: 1, administrators: 1Anyone: sign in and get an access token; start a password reset by email; set a new password after a reset. Signed-in users: check that an access token is valid. Administrators: preview the password-reset email. |
| Internal APIInternal API The part of the API for internal use: 1 operation (1 open to anyone); some are switched on only in development. | create a user | anyone: 1Anyone: create a user. Switched on only in development: create a user. |
| Users APIUsers API The part of the API for users: 10 operations (1 open to anyone, 5 for signed-in users, 4 for administrators only). | delete your own account; delete a user; list users; view your own account; view a user; update your own account; change a password; update a user; create a user; sign up for an account | anyone: 1, signed-in users: 5, administrators: 4Anyone: sign up for an account. Signed-in users: delete your own account; view your own account; view a user; update your own account; change a password. Administrators: delete a user; list users; update a user; create a user. |
| Utilities APIUtilities API The part of the API for utilities: 2 operations (1 open to anyone, 1 for administrators only). | check that the service is running; send a test email | anyone: 1, administrators: 1Anyone: check that the service is running. Administrators: send a test email. |
Source: the application's route definitions and the access checks they declare, at commit 75b4026.
Exhibit 3The main technologies, and what each one is for
| Technology | What it is | Version | Support |
|---|---|---|---|
| PythonPython Python, the programming language the application is written in. | Python, the programming language the application is written in | 3.14The language version the project declares, when it declares one. | |
| TypeScriptTypeScript TypeScript, the programming language the website is written in. | TypeScript, the programming language the website is written in | ||
| BunBun Bun, a tool used here to build the website. | Bun, a tool used here to build the website | 1The version the system's container images ask for. | |
| Python runtimePython runtime The version of Python the application runs on. | the version of Python the application runs on | 3.14The version the system's container images ask for. | |
| FastAPIFastAPI FastAPI, a Python framework for building web APIs. | FastAPI, a Python framework for building web APIs | 0.141.1The version in use, as recorded in the project's list of libraries. | |
| ReactReact React, a library for building interactive web pages. | React, a library for building interactive web pages | 19.2.8The version in use, as recorded in the project's list of libraries. | |
| TanStack RouterTanStack Router TanStack Router, which handles navigation between pages of the website. | TanStack Router, which handles navigation between pages of the website | 1.170.18The version in use, as recorded in the project's list of libraries. | |
| SQLModelSQLModel SQLModel, a library that connects the application's code to the database. | SQLModel, a library that connects the application's code to the database | 0.0.39The version in use, as recorded in the project's list of libraries. | |
| AlembicAlembic Alembic, a tool that applies changes to the database's structure in a safe order. | Alembic, a tool that applies changes to the database's structure in a safe order | 1.18.5The version in use, as recorded in the project's list of libraries. | |
| PostgreSQLPostgreSQL PostgreSQL, a widely used open-source database. | PostgreSQL, a widely used open-source database | 18The version the system's container images ask for. | |
| Tailwind CSSTailwind CSS Tailwind CSS, a styling toolkit for web pages. | Tailwind CSS, a styling toolkit for web pages | 4.3.3The version in use, as recorded in the project's list of libraries. | |
| PydanticPydantic Pydantic, a library that checks that data and settings are well-formed. | Pydantic, a library that checks that data and settings are well-formed | 2.13.4The version in use, as recorded in the project's list of libraries. | |
| TanStack QueryTanStack Query TanStack Query, which fetches and caches data from the API in the website. | TanStack Query, which fetches and caches data from the API in the website | 5.101.4The version in use, as recorded in the project's list of libraries. | |
| ViteVite Vite, a tool that packages the website's code for browsers. | Vite, a tool that packages the website's code for browsers | 8.2.0The version in use, as recorded in the project's list of libraries. | |
| TraefikTraefik Traefik, software that receives web traffic and passes each request to the right service. | Traefik, software that receives web traffic and passes each request to the right service | 3.6The version the system's container images ask for. | |
| AdminerAdminer Adminer, a web page for browsing and editing the database directly. | Adminer, a web page for browsing and editing the database directly |
Source: dependency manifests, lock files and container images, at commit 75b4026.
The system relies on 6 outside services: FastAPI CloudFastAPI Cloud A hosting service that runs FastAPI applications., GitHub ActionsGitHub Actions GitHub's service for running automated builds, tests and deployments., Let's EncryptLet's Encrypt A free service that issues the certificates websites need for secure (HTTPS) connections., SentrySentry An error-monitoring service that records crashes and errors from the live system., SmokeshowSmokeshow A service that publishes test-coverage reports from automated builds. and Email providerEmail provider The service that delivers the application's emails; which company provides it is chosen when the system is deployed.. Each is a contract, a cost and a place the system's data may go.
Exhibit 4Every outside service the system depends on
| Outside service | What it does | Used by |
|---|---|---|
| FastAPIFastAPI FastAPI, a Python framework for building web APIs. Cloud | a hosting service that runs FastAPI applications | the build and deployment pipelineThe build and deployment pipeline: the automated steps that test the system and put new versions into use. |
| GitHub Actions | GitHub's service for running automated builds, tests and deployments | the build and deployment pipelineThe build and deployment pipeline: the automated steps that test the system and put new versions into use. |
| Let's Encrypt | a free service that issues the certificates websites need for secure (HTTPS) connections | ProxyProxy: the front door for web traffic: it receives requests from the internet and passes each one to the right service; it runs Traefik. |
| Sentry | an error-monitoring service that records crashes and errors from the live system | BackendBackend: the main application: it runs the API and serves the website. |
| Smokeshow | a service that publishes test-coverage reports from automated builds | the build and deployment pipelineThe build and deployment pipeline: the automated steps that test the system and put new versions into use. |
| Email provider | the service that delivers the application's emails; which company provides it is chosen when the system is deployed | Backend, the build and deployment pipelineBackend: the main application: it runs the API and serves the website. The build and deployment pipeline: the automated steps that test the system and put new versions into use. |
Source: dependencies, configuration names, container commands and CI workflows, at commit 75b4026.
AdminerAdminer Adminer, a web page for browsing and editing the database directly. is reachable from the internet in production, through ProxyProxy The front door for web traffic: it receives requests from the internet and passes each one to the right service; it runs Traefik., and it opens the database directly. Make sure only the right people can sign in to it, or keep it off the public internet.
6 operations can be used by anyone without signing in. Through Sign-in APISign-in API The part of the API for sign-in: 5 operations (3 open to anyone, 1 for signed-in users, 1 for administrators only)., Internal APIInternal API The part of the API for internal use: 1 operation (1 open to anyone); some are switched on only in development., Users APIUsers API The part of the API for users: 10 operations (1 open to anyone, 5 for signed-in users, 4 for administrators only). and Utilities APIUtilities API The part of the API for utilities: 2 operations (1 open to anyone, 1 for administrators only)., anyone can check that the serviceservice A separately running program that is part of the system. is running, create a user (switched on only in development), set a new password after a reset, sign in and get an access tokenaccess token A temporary pass the application gives a user at sign-in, so they don't send their password with every request., sign up for an account and start a password reset by email. Everything else requires a signed-in user, and some operations an administrator.
| Open to anyone | POST /api/v1/login/access-token |
|---|---|
| Open to anyone | POST /api/v1/password-recovery/{} |
| Open to anyone | POST /api/v1/reset-password |
| Open to anyone | POST /api/v1/private/users |
| Open to anyone | POST /api/v1/users/signup |
| Open to anyone | GET /api/v1/utils/health-check |
BackendBackend The main application: it runs the API and serves the website. needs 15 settings to run, 5 of them secretsecret A setting that must stay private, such as a password or a key to an outside service. (passwords and keys). Each deployment must provide them, and the secrets must be stored safely.
| Setting | DATABASE_URL |
|---|---|
| Setting | EMAILS_FROM_EMAIL |
| Setting | FASTAPI_ENV |
| Setting | FIRST_SUPERUSER |
| Secret | FIRST_SUPERUSER_PASSWORD |
| Setting | FRONTEND_HOST |
| Secret | POSTGRES_PASSWORD |
| Setting | PROJECT_NAME |
| Secret | SECRET_KEY |
| Secret | SENTRY_DSN |
| Setting | SMTP_HOST |
| Secret | SMTP_PASSWORD |
| Setting | SMTP_PORT |
| Setting | SMTP_TLS |
| Setting | SMTP_USER |
Engineers also run MailcatcherMailcatcher A helper service for developers; used only during development. and PlaywrightPlaywright Playwright, a tool that tests the website automatically by clicking through it like a user; used only during development. while developing; these are not part of the live system.