# TALA > Internal engineering documentation for TALA — a governed digital-asset management platform built on a NestJS API and a React SPA. ## When to use these docs TALA is a governed digital-asset management platform: a NestJS 11 REST API (`backend/`) and a React 19 SPA (`frontend/`), in two independent git repositories. Reach for these docs to find an endpoint's contract, the org-scoping rules, the token lifecycle, or which parts of the API the SPA actually calls. The API reference under /reference is generated from the backend's live Swagger document and is the authoritative contract. ## Docs - [TALA engineering docs](https://docs.hqtala.com/): How TALA is built — a NestJS 11 REST API and a React 19 SPA in two independent repositories, and the contract between them. - [Quickstart](https://docs.hqtala.com/quickstart): Get both halves of TALA running against a local Postgres, including the connection traps that cost the most time. ## Architecture - [Architecture](https://docs.hqtala.com/architecture): How TALA is put together — two repositories, 14 backend modules, an exclusive user-or-organization ownership model, and a global request pipeline. - [Modules](https://docs.hqtala.com/architecture/modules): The 14 backend feature modules — where each one mounts, what it owns, and the route-ordering and scoping rules that are easy to get wrong. - [Data model](https://docs.hqtala.com/architecture/data-model): The 19 entities and 3 join tables behind TALA, the dual user-or-organization ownership chain, every enum, and the four migrations that build them. - [Request pipeline](https://docs.hqtala.com/architecture/request-pipeline): The global throttler, auth and org guards, validation pipe, activity interceptor and exception filter that every TALA request passes through. ## API - [API](https://docs.hqtala.com/api): Conventions shared by every TALA endpoint — the response envelope, error shapes, pagination, and where the authoritative reference lives. - [Conventions](https://docs.hqtala.com/api/conventions): The response envelope, error shapes, pagination semantics, and the scope parameter — the rules the generated reference does not state. - [Authentication](https://docs.hqtala.com/api/authentication): Token lifetimes, the AES-256-GCM envelope over each JWT, mandatory refresh-token rotation and its theft response, and the OAuth code exchange. - [Organizations](https://docs.hqtala.com/api/organizations): How OrganizationGuard resolves org context on every request, the two unrelated role systems, and the hashed-token invitation flow end to end. - [Uploads](https://docs.hqtala.com/api/uploads): The three-step S3 multipart pipeline — initiate, parallel PUT, complete — and the abort path that keeps S3 clean. ## Frontend - [Frontend](https://docs.hqtala.com/frontend): A React 19 SPA on Vite 7 — 17 routes, two API layers, no global state library, and a test suite that guards against mock data returning. - [Routing](https://docs.hqtala.com/frontend/routing): All 17 SPA routes plus the catch-all, the two guard components wrapping them, the three-state session machine, and the sanitiser that closes the open-redirect hole. - [API client](https://docs.hqtala.com/frontend/api-client): fetchJSON and its single-flight 401 refresh, the typed facade in api/tala.ts, and the per-feature hooks that predate it — including their known gaps. - [Data shapes](https://docs.hqtala.com/frontend/types): Every domain interface the SPA receives from api/tala.ts, what each endpoint returns, and the three shapes that mislead you if you skim them. - [Adding a feature](https://docs.hqtala.com/frontend/recipes): Wiring a new endpoint into the SPA end to end — where the call goes, how to load it, how to handle every failure, and the six mistakes that cost the most time. ## Operations - [Operations](https://docs.hqtala.com/operations): Branch model, environments, CI gates, and deployment state for TALA — including what is unenforced, why, and what is not deployed at all. - [Branching](https://docs.hqtala.com/operations/branching): Three long-lived branches, forward-only merges, the drift guard that exists because of a real incident, and why CI's lint and test gates are muted. - [Environments](https://docs.hqtala.com/operations/environments): Three environments mapped onto three branches, the TLS rules for each, and the Supabase connection traps and RLS lockdown that are not optional. - [Deployment](https://docs.hqtala.com/operations/deployment): Nothing is currently deployed. What GitHub Pages did wrong, what was torn down, and the four things to settle before the Openship cutover. ## Status - [Status](https://docs.hqtala.com/status): What is built, what is wired, and where the project's own documentation disagrees with its code — both read from source rather than from an existing document. - [What's wired](https://docs.hqtala.com/status/integration): 55 of 74 backend routes have a frontend caller. The 19 that do not, which of them actually matter, and the contract gaps found alongside them. - [Documentation drift](https://docs.hqtala.com/status/drift): Ten specific claims in CLAUDE.md that the code no longer supports, which claims still hold, and the tooling that keeps these docs from drifting too. ## Reference - [TALA API Documentation](https://docs.hqtala.com/reference) ### App - [Liveness probe](https://docs.hqtala.com/reference/app/app-controller-get-hello) ### Asset - [Delete an asset by its ID](https://docs.hqtala.com/reference/asset/asset-controller-delete-asset) - [Favorite or unfavorite an asset](https://docs.hqtala.com/reference/asset/asset-controller-favorite) - [Get a presigned download URL for an asset](https://docs.hqtala.com/reference/asset/asset-controller-download) - [Get asset details by ID](https://docs.hqtala.com/reference/asset/asset-controller-get-asset-by-id) - [List assets in the current scope](https://docs.hqtala.com/reference/asset/asset-controller-list) - [Publish a personal asset into the organization](https://docs.hqtala.com/reference/asset/asset-controller-publish) - [Restore a specific version of an asset](https://docs.hqtala.com/reference/asset/asset-controller-restore-version) - [Retrieve activity logs for a single asset](https://docs.hqtala.com/reference/asset/asset-controller-get-logs-by-asset) - [Retrieve all versions of an asset](https://docs.hqtala.com/reference/asset/asset-controller-get-versions) - [Retrieve assets belonging to a specific collection](https://docs.hqtala.com/reference/asset/asset-controller-paginate-assets-by-collection) - [Retrieve the caller's asset activity logs](https://docs.hqtala.com/reference/asset/asset-controller-get-my-logs) - [Update an asset](https://docs.hqtala.com/reference/asset/asset-controller-update-asset) ### Auth - [Begin GitHub OAuth sign-in](https://docs.hqtala.com/reference/auth/auth-controller-github-auth) - [Begin Google OAuth sign-in](https://docs.hqtala.com/reference/auth/auth-controller-google-auth) - [Changes the user password on the reset-password page. Side effect: a successful reset REVOKES ALL of the user’s existing sessions — every other device will get 401 on its next refresh and must re-login.](https://docs.hqtala.com/reference/auth/auth-controller-reset-password) - [Exchanges the one-time code from the OAuth success redirect (?code=...) for a session. The code is single-use and expires in ~60s. Returns the same shape as login. Replaces returning tokens directly in the OAuth redirect URL.](https://docs.hqtala.com/reference/auth/auth-controller-exchange-o-auth-code) - [GitHub OAuth callback — redirects to the SPA with a single-use code](https://docs.hqtala.com/reference/auth/auth-controller-github-callback) - [Google OAuth callback — redirects to the SPA with a single-use code](https://docs.hqtala.com/reference/auth/auth-controller-google-callback) - [POST the current refresh token in the body to receive a NEW access token and a ROTATED refresh token. The presented refresh token is single-use and immediately revoked — the client must persist the returned refreshToken. (Replaces the old GET + `ref-tk` header contract.)](https://docs.hqtala.com/reference/auth/auth-controller-refresh-access-token) - [Revokes the session for the supplied refresh token. Idempotent — always returns 200, even for an invalid or expired token, so token validity is never disclosed.](https://docs.hqtala.com/reference/auth/auth-controller-logout) - [This endpoint is only to be used on the forgot password page to request a password reset](https://docs.hqtala.com/reference/auth/auth-controller-request-password-reset) - [This endpoint is only to be used on the register page](https://docs.hqtala.com/reference/auth/auth-controller-register) - [This endpoint is only to be used on the reset password page but before loading the screen to verify if the token provided by the user is valid or not](https://docs.hqtala.com/reference/auth/auth-controller-verify-token) - [This endpoint is only to be used to get the authenticated user](https://docs.hqtala.com/reference/auth/auth-controller-get-authenticated-user) - [This endpoint is only to be used when a user wants to login](https://docs.hqtala.com/reference/auth/auth-controller-login) - [This endpoint is to be used after creating account to verify the email used before access to the system](https://docs.hqtala.com/reference/auth/auth-controller-verify-email) ### Collection - [Delete a collection by its ID](https://docs.hqtala.com/reference/collection/collection-controller-delete-collection) - [Favorite or unfavorite a collection](https://docs.hqtala.com/reference/collection/collection-controller-favorite) - [Get a single collection by its ID](https://docs.hqtala.com/reference/collection/collection-controller-get-collection-by-id) - [Get all collections belonging to a user](https://docs.hqtala.com/reference/collection/collection-controller-paginate) - [This endpoint is used to create a collection for a user](https://docs.hqtala.com/reference/collection/collection-controller-create-collection) - [Update the title of a collection](https://docs.hqtala.com/reference/collection/collection-controller-update-collection) ### Dashboard - [Retrieve the organization dashboard summary](https://docs.hqtala.com/reference/dashboard/dashboard-controller-summary) ### Organization - [Accept an organization invitation](https://docs.hqtala.com/reference/organization/organization-controller-accept) - [Create an organization](https://docs.hqtala.com/reference/organization/organization-controller-create) - [Invite a member to the organization](https://docs.hqtala.com/reference/organization/organization-controller-invite) - [List organization members](https://docs.hqtala.com/reference/organization/organization-controller-members) - [List organizations the caller belongs to](https://docs.hqtala.com/reference/organization/organization-controller-list) - [Remove a member from the organization](https://docs.hqtala.com/reference/organization/organization-controller-remove-member) - [Rename an organization](https://docs.hqtala.com/reference/organization/organization-controller-update) - [Retrieve an invitation by token](https://docs.hqtala.com/reference/organization/organization-controller-invitation) - [Retrieve an organization by id](https://docs.hqtala.com/reference/organization/organization-controller-get) - [Update a member's role or status](https://docs.hqtala.com/reference/organization/organization-controller-update-member) ### Plan - [Get all plans](https://docs.hqtala.com/reference/plan/plan-controller-find-all) ### Profile - [Finalize an avatar upload](https://docs.hqtala.com/reference/profile/profile-controller-complete) - [Get a presigned URL for an avatar upload](https://docs.hqtala.com/reference/profile/profile-controller-avatar-upload) - [Update the caller profile](https://docs.hqtala.com/reference/profile/profile-controller-update) ### Project - [Create a project](https://docs.hqtala.com/reference/project/project-controller-create) - [Delete a project](https://docs.hqtala.com/reference/project/project-controller-remove) - [List projects in the organization](https://docs.hqtala.com/reference/project/project-controller-list) - [Reorder a project](https://docs.hqtala.com/reference/project/project-controller-move) - [Retrieve a project by id](https://docs.hqtala.com/reference/project/project-controller-get) - [Update a project](https://docs.hqtala.com/reference/project/project-controller-update) ### Task - [Create a task in a project](https://docs.hqtala.com/reference/task/task-controller-create) - [Delete a task](https://docs.hqtala.com/reference/task/task-controller-remove) - [List tasks in a project](https://docs.hqtala.com/reference/task/task-controller-by-project) - [List tasks in the organization](https://docs.hqtala.com/reference/task/task-controller-list) - [Move a task to another column or position](https://docs.hqtala.com/reference/task/task-controller-move) - [Replace a task's assignees](https://docs.hqtala.com/reference/task/task-controller-assignees) - [Retrieve a task by id](https://docs.hqtala.com/reference/task/task-controller-get) - [Update a task](https://docs.hqtala.com/reference/task/task-controller-update) ### TaskComment - [Delete a task comment](https://docs.hqtala.com/reference/taskcomment/task-comment-controller-remove) - [Edit a task comment](https://docs.hqtala.com/reference/taskcomment/task-comment-controller-update) - [List comments on a task](https://docs.hqtala.com/reference/taskcomment/task-comment-controller-list) - [Post a comment on a task](https://docs.hqtala.com/reference/taskcomment/task-comment-controller-create) ### Timeline - [Get a user activity logs](https://docs.hqtala.com/reference/timeline/activity-logs-controller-paginate-my-activity) - [Get action summary counts (admin)](https://docs.hqtala.com/reference/timeline/activity-logs-controller-get-action-summary) - [Get all activity logs (admin)](https://docs.hqtala.com/reference/timeline/activity-logs-controller-paginate-all) - [Get logs for a specific resource (admin)](https://docs.hqtala.com/reference/timeline/activity-logs-controller-paginate-by-resource) ### Upload - [Abort an active multipart upload](https://docs.hqtala.com/reference/upload/upload-controller-abort-upload) - [Complete multipart upload and save asset metadata](https://docs.hqtala.com/reference/upload/upload-controller-complete-upload) - [Initiate a multipart upload to S3](https://docs.hqtala.com/reference/upload/upload-controller-initiate-upload) ## Agent resources - [llms-full.txt](https://docs.hqtala.com/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://docs.hqtala.com/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://docs.hqtala.com/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://docs.hqtala.com/openapi.json. - [API catalog](https://docs.hqtala.com/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [agent-readability.json](https://docs.hqtala.com/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://docs.hqtala.com/sitemap.xml): Every indexable page URL with its last-modified date.