# Architecture

Four deployables over one shared database, in one pnpm + Turborepo monorepo.

| App | Package | Domain | Runtime | Owns |
| --- | --- | --- | --- | --- |
| `apps/api` | `acrune-api` | **acrune.com** | Hono | Marketing site and API; proxies `/dashboard`; the auth / org / email tables |
| `apps/dashboard` | `acrune-dashboard` | **acrune.com/dashboard** | Next.js | The operator UI and these docs. No schema of its own |
| `apps/track` | `acrune-track` | **track.acrune.com** | Hono | The tracker: redirects, `/v1`, `/admin`, and the tracking tables |
| `apps/engine` | `acrune-engine` | AWS, via SST | Lambda + SQS | Durable background work. Skeleton today |

The apex reverse-proxies `/dashboard/:path*` to the dashboard's Vercel
deployment, so the two share `acrune.com` and a host-only session cookie
without widening the cookie domain to a subdomain.

## Ownership is disjoint, deliberately

Each app defines only its own tables:

- `apps/api` — `users`, `sessions`, `login_tokens`, `organizations`,
`organization_members`, `applications`, `email_opt_outs`,
`request_counters`, `scheduled_emails`
- `apps/track` — `accounts`, `campaigns`, `creators`, `links`, `clicks`,
`post_metrics`, `api_keys`, `admin_keys`, `audit_log`, `api_key_usage`, plus
the legacy ledger and conversion tables that live only in raw migrations
- `apps/dashboard` — none. It reads the above through **raw SQL**, on purpose:
a second Drizzle definition of another app's tables silently drifts from the
first

Never define or write another app's tables from your app.

## Why there are no shared packages

There is no `packages/*` in this repo, and that is a decision rather than an
omission.

Because ownership is disjoint, the apps have very little in common: they share
a database URL and nothing else. A shared package added before real duplication
exists buys nothing and costs a build edge, a version, and a reason for two
apps to be released together.

Extract one the first time two apps genuinely need the same code. Not before.

## Why the tracker is its own deployable

The redirect is the only hot path in the system and the only one where latency
is the product — a slow redirect is a lost click. Keeping it on its own domain,
in its own function, with one read and one write, means nothing the dashboard
does can slow it down, and a bad deploy of the marketing site cannot take
measurement offline.

It also keeps the surface a partner integrates against separate from the
surface a person logs into.

## Why the engine is on AWS and not Vercel

Vercel request functions cap at 30 seconds. That is right for a redirect and
wrong for an unbounded batch job over every row in a table.

The engine exists for the work that has not shipped yet — hold settlement, a
fraud scan, attribution recompute — and is a skeleton until one of them does.
The rule it encodes: the web tier stays on Vercel, the data stays on Neon, and
only genuinely long-running work moves. See
[Scalability](https://acrune.com/dashboard/docs/engineering/scalability.md) for the trigger.

## Testing

`apps/track` and `apps/api` run their route handlers and middleware against an
in-process Postgres (`pglite`) rather than mocks, injected through a test seam
on the database client. The real SQL runs; only the host changes.

The tracker's schema is mirrored as DDL in the test helper rather than read
from the migrations. If a column changes in one and not the other, a test
fails — which is the point.
