Admin Portal¶
The staff admin for CookieHub — accounts, domains, users, invoices, subscriptions, quotes, VAT settlement and the rest
of what core's /cha panel does. It is a Next.js port of that panel (cookiehub-com/admin) that works directly on
core's MariaDB database, so it has no API of its own and nothing in core had to change for it. Core's /cha keeps
working alongside it.
Architecture¶
- Next.js 16 (App Router, React 19, TypeScript), rendered on the server. Pages are Server Components that read
through a
services/*.service.tslayer; writes are Server Actions calling the same layer. - Prisma 7 with the MariaDB driver adapter, against core's
coredatabase. The schema is introspected from core (prisma db pull), never migrated from here — a schema change is a core migration. - Auth is core's. The
chtokencookie and thetokenstable are shared with the Laravel dashboard, and onlyusers.adminaccounts with a two-factor secret get in (TOTP against core'sotphpsecrets). A session here is the same kind of session as in core. - Outbound mail goes through Amazon SES over SMTP with the identity core sends as. PDFs — invoice, quote, VAT return, statement of account — are drawn in-process with pdfkit.
- Hardening: a per-request CSP nonce, fixed security headers, and a TLS-verified connection to RDS with the Amazon RDS CA bundle compiled in (the MariaDB connector would otherwise talk in the clear).
What is ported, what is still read-only and what is missing is tracked in the repo's TODO.md.
Deployment¶
One container per environment on the core ECS clusters, behind an ALB. Terraform (infra) owns the service, the task
definition, the ECR repository, the SSM parameters and the deploy roles; the repo owns the image and the workflow.
| Stage | Production | |
|---|---|---|
| AWS account | 258618559895 |
759286286879 |
| ECR repo | admin-portal |
admin-portal |
| ECS cluster | stage-euc1-core-ecs-cluster |
prod-euc1-core-ecs-cluster |
| ECS service | admin-portal |
admin-portal |
| Task definition | stage-euc1-core-admin-portal |
prod-euc1-core-admin-portal |
| Container | admin-portal, port 3000 |
admin-portal, port 3000 |
| Health check | GET /api/health |
GET /api/health |
| Database | core MariaDB (RDS), core |
core MariaDB (RDS), core |
| SSM params | /core/stage/admin-portal/* |
/core/prod/admin-portal/* |
| Deployed by | push to main |
published v* release, behind the production gate |
The health check answers 200 without a session or a database query, on purpose: a database blip must not make ECS
cycle every task. The pages report database trouble on their own.
Hostnames
The stage and production hostnames are not recorded here yet — they are the ALB listeners in infra.
CI/CD¶
One workflow, Deploy, in cookiehub-com/admin. The trigger picks the environment:
- A push to
maindeploys stage (admin has nostagebranch, IS-133); a publishedv*release deploys production, after a reviewer approves it at theproductionenvironment. - The job assumes that environment's
gh-oidc-deploy-admin-portalrole via GitHub OIDC and pushes the image to that account's ECR as<sha>,latestand, on a release, the tag. - It reads the live task definition, swaps only the container image, registers a new revision and updates the service, waiting for it to stabilise. Everything else in the task definition stays as Terraform put it.
Like vault-api, core-api, atrax, atrax-api and vault-ingest (and unlike edge-api), the task definition is not pinned to latest: every deploy is a new revision, so a rollback
is update-service --task-definition <family>:<revision> and re-tags nothing.
See the Deployment runbook for status checks, logs, rollback and the repository settings the workflow reads.
Tech Stack¶
| Layer | Technology |
|---|---|
| Runtime | Node.js 22 (node:22-bookworm-slim), non-root |
| Framework | Next.js 16 (App Router, Turbopack), React 19, TypeScript strict |
| ORM | Prisma 7 + @prisma/adapter-mariadb |
| Styling | CSS custom-property tokens + CSS Modules, no UI kit |
| pdfkit | |
| nodemailer → Amazon SES (SMTP, STARTTLS) | |
| Container | Docker multi-stage, Next standalone output (~400 MB, ~230 of it Node) |
Configuration¶
The container reads these from its environment. The task definition maps the secrets from SSM and sets the plain ones
inline; NODE_ENV, PORT and HOSTNAME come from the image.
| Variable | Required | Notes |
|---|---|---|
DATABASE_URL |
yes | mysql://USER:PASSWORD@HOST:3306/core. TLS to RDS needs nothing in the URL. The user needs write on tokens (login writes the session row) and on what the ported write actions touch. |
AUTH_SECRET |
yes | Signs the short-lived cookie between password and two-factor code. Unset, every task generates its own and two tasks reject each other's half-finished logins. |
MAIL_USERNAME / MAIL_PASSWORD |
yes in prod | SES SMTP credentials, the pair core sends with. MAIL_DRIVER defaults to smtp on a production build and SES refuses an unauthenticated session. |
MAIL_DRIVER |
no | log writes mail to the log instead of sending — the right value for stage unless mail is what is being tested. |
MAIL_HOST / MAIL_PORT / MAIL_ENCRYPTION / MAIL_FROM_ADDRESS / MAIL_FROM_NAME |
no | Default to SES eu-central-1 on 587/STARTTLS, from support@cookiehub.com. |
BORGUN_URL, BORGUN_TRANSACTION_TYPE, BORGUN_PRIVATE_KEY, BORGUN_CH_PRIVATE_KEY |
no | "Pay Now" on the invoice page. The URL defaults to the test gateway; unset keys hide the button. |
CHARTMOGUL_API_KEY |
no | The dashboard's metrics box; unset it says "not connected". |
NEXT_PUBLIC_DASH_URL |
no | Where "View in Dash" links go; default https://dash.cookiehub.com. |
See Secrets for the SSM side.
Dependencies¶
- core MariaDB (RDS) — the same
coredatabase the Laravel dashboard uses; the only data store. - Amazon SES — outbound mail (the reseller welcome, the Send Mail composer), over SMTP.
- Borgun / Teya RPG (optional) — card payments from the invoice page.
- ChartMogul (optional) — ARR / subscriber metrics on the dashboard.
- Dash (
dash.cookiehub.com) — linked out to for "View in Dash" and two-factor enrolment; never called server-side.
Local Development¶
The repo's README.md covers it: npm install, a .env.local with a DATABASE_URL for a core database (see
Core Dev Database), npm run db:pull && npm run db:generate, then npm run dev.
MAIL_DRIVER is log outside production builds, so a write tried locally never mails a customer.