Skip to content

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.ts layer; writes are Server Actions calling the same layer.
  • Prisma 7 with the MariaDB driver adapter, against core's core database. 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 chtoken cookie and the tokens table are shared with the Laravel dashboard, and only users.admin accounts with a two-factor secret get in (TOTP against core's otphp secrets). 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:

  1. A push to main deploys stage (admin has no stage branch, IS-133); a published v* release deploys production, after a reviewer approves it at the production environment.
  2. The job assumes that environment's gh-oidc-deploy-admin-portal role via GitHub OIDC and pushes the image to that account's ECR as <sha>, latest and, on a release, the tag.
  3. 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
PDF pdfkit
Mail 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 core database 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.