TALA engineering docs
How TALA is built — a NestJS 11 REST API and a React 19 SPA in two independent repositories, and the contract between them.
TALA is a governed digital-asset management platform. Assets live in S3 behind CloudFront; everything about who owns them, who may see them, and what happened to them lives in Postgres behind a NestJS API.
These are internal engineering docs. They cover the shape of the system, the contract between its two halves, and the parts that are built but not yet reachable from the UI. They are not user documentation and not a product spec.
Run it locally
Both halves up in about ten minutes, including the Postgres traps.
API reference
Every operation, generated from the backend’s live Swagger document.
Architecture
Modules, the data model, and the request pipeline.
What's wired
Which endpoints the SPA actually calls, and which it doesn’t.
Beyond those: API conventions covers the envelope, errors and pagination that the generated reference does not state; Frontend covers the SPA’s routing and API client; and Operations covers branching, environments and the deployment plan.
The two repositories
TALA is one product in two independent git repositories, checked out side by side under a parent folder that is not itself a repository.
- TALA/
- backend/ — NestJS 11 REST API ·
TalaHqq/tala-backend - frontend/ — React 19 SPA ·
TalaHqq/tala-frontend - docs/ — this Blume site
- CLAUDE.md
- backend/ — NestJS 11 REST API ·
Changes to one repo do not affect the other. There is no shared package, no generated client, and no compile-time link between them — the only contract is HTTP, which is why the API reference is generated from the running server rather than written by hand.
What the system is made of
| Backend | Frontend | |
|---|---|---|
| Framework | NestJS 11, TypeScript 5.7 | React 19, Vite 7, TypeScript 5.9 |
| Runtime | Node v22.16.0 (.nvmrc) |
— |
| Data | PostgreSQL via TypeORM 0.3 | none; server is the source of truth |
| Storage | AWS S3 multipart, CloudFront | presigned PUT direct to S3 |
| Auth | JWT (HS256) inside AES-256-GCM, rotating refresh tokens | tokens in localStorage |
| Styling | — | Tailwind CSS v4, shadcn/ui, @base-ui/react |
| State | — | component useState and bespoke hooks |
| Tests | Jest, unit + e2e | Vitest |
Where the numbers come from
Every count in these docs was read from source, not from an older document.
| Backend modules | 14 feature modules plus the app root |
| HTTP routes declared | 74 |
| Operations in the published spec | 73 — GET /api/seeder carries @ApiExcludeController |
| Entities | 19, plus 3 join tables |
| Migrations | 4 |
| SPA routes | 17 |
| Routes with a frontend caller | 55 of 74 |