Internal developer overview
On this page
dembrane is one Bun and TypeScript backend on PostgreSQL, and one React frontend. Each page in this section gives you the shape of one part in a few screens, then names the file in the repository that decides the detail.
If you integrate with dembrane or run it yourself, start at the external developer guide.
The stack in one screen#
- Five apps deploy:
api,worker,media,webandmigrate. Each builds to one compiled binary. - The apps are built from packages in three layers. Apps sit on top. Namespaces are the product areas. Capabilities are building blocks with no business rules.
- PostgreSQL is the only stateful service the platform needs. Jobs, schedules, live events, presence and rate limits all run on it. Audio and files live in S3-compatible object storage.
- There is no Redis, no Directus service, no Python process and no separate agent service.
- The frontend is one React and Vite codebase. It serves both the dashboard and the participant portal.
- Language models run on Google Vertex AI. Features ask for a model group, never a vendor model name.
Architecture explains each line.
The repository at a glance#
| Path | What is in it |
|---|---|
dembrane/platform |
The backend. apps/ holds the five programs and packages/ the libraries they are built from. legacy/ holds what exists only because of the previous stack. Nothing in it ships in an image. |
dembrane/frontend |
The dashboard and the participant portal. |
dembrane/infra |
Terraform for the preview, staging and production environments. |
.github/workflows, .github/scripts |
The checks, the image builds and the deploys. |
docs |
This documentation. |
dembrane-go |
The iOS app. |
brand, skills |
Logos and style assets, and the brand guidelines agents follow when they write for dembrane. |
Where to read next#
| You want to | Read |
|---|---|
| Run it on your machine | Local development |
| See how the apps and packages fit together | Architecture |
| Find a table | The data model |
| Follow audio from upload to summary | The processing pipeline |
| Add or debug a job | Background jobs and schedules |
| Work on Ask or the assistant | Chat and the assistant |
| Change who may do what | Roles and policies in code |
| Add or change a free plan limit | The free tier in code |
| Ship a change | Deployment and releases |
| Change a page of these docs | Maintaining the docs |
The files that decide#
These pages summarise. The files below are the source of truth, so check them when a page and the code disagree.
| File | What it settles |
|---|---|
dembrane/platform/README.md |
How to run the platform, what each app is, the layer rule, and where to start reading. |
dembrane/platform/PACKAGES.md |
Every app and package with a one-line description, and which namespace may import which. It is generated. Do not edit it by hand. |
dembrane/platform/packages/config/src/schema.ts |
Every setting, with its description and default. |
dembrane/platform/packages/db/src/schema/ |
Every table. |
dembrane/infra/README.md |
The environments and what runs in each. |
.github/workflows/platform.yml |
The checks on a pull request and how each environment is deployed. |
CONTRIBUTING.md, TRANSLATING.md |
How to contribute code and translations. |
Conventions worth knowing early#
- Run
bun run checkindembrane/platformbefore you push. It runs the lint, the type check, the layer rule and the tests. - A dependency points down only: apps, then namespaces, then capabilities.
bun run packages checkfails when a package breaks this. - Code reads a setting as
config.<section>.<key>. A setting that is not declared in the schema is a type error. - A table changes in the Drizzle schema first.
bun run db:generatewrites the migration, and CI fails when the schema and the migrations disagree. - A job is defined in its namespace and run by the worker. A service can enqueue a job inside its database transaction, so the job exists only if the change commits.
- Access to a workspace or a project is decided by policies in
packages/access. A route asks for a policy by name. - A change to the product changes its docs page in the same pull request.
- Your first pull request adds your GitHub username to
contributors.yml. That is how you sign the contributor licence agreement. See contributing.
Related#
- Architecture
- Local development
- Deployment and releases
- The free tier in code
- External developer guide
- Contributing
- Licensing
Comments