Local development

.agents/AGENTS.md

@@ -1,16 +1,16 @@
 # Agent Guidelines
 
 ## Commands
-- Build all: `pnpm build` — Dev all: `pnpm dev` — Docker: `just dev up` / `just dev down` / `just dev reset`
-- CI build (local): `just build` — runs Biome check + build in Docker (no Node.js required on host)
-- Lint all: `pnpm check` (runs Biome check) — Fix: `pnpm check:fix`
-- Format all: `pnpm format` — Fix: `pnpm format:fix`
-- Lint only: `pnpm lint` — Fix: `pnpm lint:fix`
+- Build all: `pnpm build` - Dev all: `pnpm dev` - Docker: `just dev up` / `just dev down` / `just dev reset`
+- CI build (local): `just build` - runs Biome check + build in Docker (no Node.js required on host)
+- Lint all: `pnpm check` (runs Biome check) - Fix: `pnpm check:fix`
+- Format all: `pnpm format` - Fix: `pnpm format:fix`
+- Lint only: `pnpm lint` - Fix: `pnpm lint:fix`
 - Typecheck website: `packages/website/node_modules/.bin/tsc --noEmit --project packages/website/tsconfig.json`
 - No test framework exists in this repository.
 
 ## Monorepo Layout
-`packages/{api, website, metadata, tools, ui}` — all ESM (`"type": "module"`), TypeScript strict mode.
+`packages/{api, website, metadata, tools, ui}` - all ESM (`"type": "module"`), TypeScript strict mode.
 - **api** (`@arrhes/application-api`): Hono backend, Drizzle ORM, PostgreSQL, Nodemailer, Puppeteer, S3
 - **website** (`@arrhes/application-website`): React 19, TanStack Router/Query/Table, React Hook Form, Radix UI primitives, Panda CSS
 - **metadata** (`@arrhes/application-metadata`): Shared models, schemas (valibot), route definitions. Consumed via subpath exports (`@arrhes/application-metadata/models`, `/schemas`, `/routes`, `/components`)
@@ -22,7 +22,7 @@
 - **Files**: all `camelCase.ts[x]` (including components). Barrel files are `_index.ts`.
 - **Exports**: components `PascalCase` functions, models/schemas/utilities `camelCase`. Models use `Model` suffix (`accountModel`), schemas have no suffix.
 - **Components**: one exported React component per file. Private helper functions are fine in the same file, but not other components.
-- **Validation**: `import * as v from "valibot"` — use `v.object()`, `v.string()`, `v.InferOutput<>`.
+- **Validation**: `import * as v from "valibot"` - use `v.object()`, `v.string()`, `v.InferOutput<>`.
 - **Styling**: Panda CSS via `css()` and `cx()` from `@arrhes/ui/utilities/cn.js`.
 - **IDs**: nanoid with custom alphabet, 16 chars.
 - **Error handling**: try/catch with structured logging in API; toast notifications in website; structured error responses via Hono.

.github/workflows/publish-packages.yml

@@ -49,14 +49,14 @@ jobs:
           VITE_API_BASE_URL: ${{ vars.VITE_API_BASE_URL }}
           VITE_WEBSITE_BASE_URL: ${{ vars.VITE_WEBSITE_BASE_URL }}
         run: |
-          docker compose -f .workflows/.build/compose.yml build ci
-          docker compose -f .workflows/.build/compose.yml build api website
+          docker compose -f .workflows/build/compose.yml build ci
+          docker compose -f .workflows/build/compose.yml build api website admin
 
       - name: Tag and push images
         env:
           VERSION: ${{ steps.version.outputs.version }}
         run: |
-          IMAGES=("api" "website")
+          IMAGES=("api" "website" "admin")
 
           for img in "${IMAGES[@]}"; do
             SRC="arrhes-${img}:${VERSION}"

.gitignore

@@ -7,12 +7,13 @@ build
 .continue
 .old
 .vscode
+.agents
 
-.pnpm-store
+.pnpm-store
 
 *.tsbuildinfo
 
-styled-system
-
-test-results
+styled-system
+
+test-results
 playwright-report

.workflows/.build/compose.yml → .workflows/build/compose.yml

@@ -8,29 +8,38 @@
 #   ci        - Lint + unit tests + build (gate before packaging)
 #   api       - Production API image
 #   website   - Production Website image (nginx + static)
+#   admin     - Production Admin image (nginx + static)
 #
 # Usage:
-#   docker compose -f .workflows/.build/compose.yml build ci
-#   docker compose -f .workflows/.build/compose.yml build api website
+#   docker compose -f .workflows/build/compose.yml build ci
+#   docker compose -f .workflows/build/compose.yml build api website admin
 # ==============================================================================
 
 services:
   ci:
     build:
       context: ../..
-      dockerfile: .workflows/.build/packages/ci/Dockerfile
+      dockerfile: .workflows/build/packages/ci/Dockerfile
 
   api:
     image: arrhes-api:${ARRHES_VERSION:-dev}
     build:
       context: ../..
-      dockerfile: .workflows/.build/packages/api/Dockerfile
+      dockerfile: .workflows/build/packages/api/Dockerfile
 
   website:
     image: arrhes-website:${ARRHES_VERSION:-dev}
     build:
       context: ../..
-      dockerfile: .workflows/.build/packages/website/Dockerfile
+      dockerfile: .workflows/build/packages/website/Dockerfile
       args:
         - VITE_WEBSITE_BASE_URL=${VITE_WEBSITE_BASE_URL:-}
         - VITE_API_BASE_URL=${VITE_API_BASE_URL:-}
+
+  admin:
+    image: arrhes-admin:${ARRHES_VERSION:-dev}
+    build:
+      context: ../..
+      dockerfile: .workflows/build/packages/admin/Dockerfile
+      args:
+        - VITE_API_BASE_URL=${VITE_API_BASE_URL:-}

.workflows/build/packages/admin/Dockerfile

@@ -0,0 +1,31 @@
+# Use an official Node.js image to build our image from
+FROM node:25-alpine AS base
+RUN npm install -g pnpm@10.26.1
+ENV NODE_OPTIONS="--max-old-space-size=4096"
+
+# Build the repo
+FROM base AS build
+
+# Build arguments for Vite environment variables
+ARG VITE_API_BASE_URL
+
+WORKDIR /root
+COPY . .
+RUN pnpm install
+
+# Write VITE_* build args to .env so Vite can read them during build.
+# Vite reads import.meta.env from .env files, not from process.env.
+RUN printf "VITE_API_BASE_URL=%s\n" \
+    "$VITE_API_BASE_URL" \
+    > packages/admin/.env
+
+RUN pnpm run build
+
+# Start application
+FROM nginx:alpine AS deploy
+WORKDIR /
+COPY .workflows/build/packages/admin/nginx/default.conf /etc/nginx/nginx.conf
+RUN rm -rf /usr/share/nginx/html/*
+COPY --from=build /root/packages/admin/build /usr/share/nginx/html
+EXPOSE 3102
+CMD ["nginx"]

.workflows/.build/packages/website/nginx/default.conf → .workflows/build/packages/admin/nginx/default.conf

@@ -26,7 +26,7 @@ http {
     index index.html;
 
     # Immutable hashed assets (JS, CSS, fonts, images) - cache for 1 year
-    location ~* \.(?:js|css|woff2?|ttf|eot|svg|png|jpg|jpeg|gif|webp|ico|webmanifest)$ {
+    location ~* \.(?:js|css|woff2?|ttf|eot|svg|png|jpg|jpeg|gif|webp|webmanifest)$ {
       add_header Cache-Control "public, max-age=31536000, immutable";
       try_files $uri =404;
     }
@@ -37,4 +37,4 @@ http {
       try_files $uri $uri/ /index.html =404;
     }
   }
-}
+}

.workflows/.build/packages/ci/Dockerfile → .workflows/build/packages/ci/Dockerfile

@@ -26,8 +26,8 @@ RUN pnpm install --frozen-lockfile
 # Build all packages (must run before tests so workspace deps are compiled)
 RUN pnpm run build
 
-# Run Biome check (lint + format)
-RUN pnpm check
+# Auto-format, then run Biome check (lint)
+RUN pnpm format:fix && pnpm check
 
 # Run unit tests
 RUN pnpm --recursive --if-present --filter='./packages/**' run test:unit

.workflows/build/packages/website/.dockerignore

@@ -0,0 +1,17 @@
+# Include any files or directories that you don't want to be copied to your
+# container here (e.g., local build artifacts, temporary files, etc.).
+#
+# For more help, visit the .dockerignore file reference guide at
+# https://docs.docker.com/go/build-context-dockerignore/
+
+**/.dockerignore
+**/.env
+**/.vscode
+**/.git
+**/.gitignore
+**/docker-compose*
+**/compose*
+**/Dockerfile*
+**/node_modules
+**/build
+README.md

.workflows/.build/packages/website/Dockerfile → .workflows/build/packages/website/Dockerfile

@@ -25,7 +25,7 @@ RUN pnpm run build
 # Start application
 FROM nginx:alpine AS deploy
 WORKDIR /
-COPY .workflows/.build/packages/website/nginx/default.conf /etc/nginx/nginx.conf
+COPY .workflows/build/packages/website/nginx/default.conf /etc/nginx/nginx.conf
 RUN rm -rf /usr/share/nginx/html/*
 COPY --from=build /root/packages/website/build /usr/share/nginx/html
 EXPOSE 3101

.workflows/build/packages/website/nginx/default.conf

@@ -0,0 +1,45 @@
+# default.conf
+worker_processes auto;
+
+daemon off;
+
+events {
+  worker_connections 1024;
+}
+
+http {
+  include mime.types;
+
+  server {
+    listen 80;
+
+    gzip on;
+    gzip_http_version 1.1;
+    gzip_disable      "MSIE6";
+    gzip_min_length   256;
+    gzip_vary         on;
+    gzip_proxied      any;
+    gzip_types        text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript font/woff2;
+    gzip_comp_level   9;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Unhashed public assets (favicon, OG images) - cache for 1 day
+    location = /favicon.ico { add_header Cache-Control "public, max-age=86400"; try_files $uri =404; }
+    location = /og.png      { add_header Cache-Control "public, max-age=86400"; try_files $uri =404; }
+    location = /og.webp     { add_header Cache-Control "public, max-age=86400"; try_files $uri =404; }
+
+    # Immutable hashed assets (JS, CSS, fonts, images) - cache for 1 year
+    location ~* \.(?:js|css|woff2?|ttf|eot|svg|png|jpg|jpeg|gif|webp|webmanifest)$ {
+      add_header Cache-Control "public, max-age=31536000, immutable";
+      try_files $uri =404;
+    }
+
+    # HTML and other mutable files - always revalidate
+    location / {
+      add_header Cache-Control "no-cache";
+      try_files $uri $uri/ /index.html =404;
+    }
+  }
+}

.workflows/.dev/README.md → .workflows/dev/README.md

@@ -5,7 +5,7 @@ Docker-based development environment for the Arrhes application.
 ## Architecture
 
 ```
-.workflows/.dev/
+.workflows/dev/
 ├── compose.yml              # Docker Compose config (services + env vars)
 ├── compose.tunnel.yml       # Cloudflare tunnel overlay
 ├── .dockerignore            # Build context exclusions
@@ -63,30 +63,30 @@ pnpm install
 just dev up
 
 # Or with Docker Compose directly
-docker compose -f .workflows/.dev/compose.yml up -d
+docker compose -f .workflows/dev/compose.yml up -d
 ```
 
 ### Rebuild images (after Node.js or PNPM version changes)
 ```bash
-docker compose -f .workflows/.dev/compose.yml build
-docker compose -f .workflows/.dev/compose.yml up -d
+docker compose -f .workflows/dev/compose.yml build
+docker compose -f .workflows/dev/compose.yml up -d
 ```
 
 ### View logs
 ```bash
 # All services
-docker compose -f .workflows/.dev/compose.yml logs -f
+docker compose -f .workflows/dev/compose.yml logs -f
 
 # Specific service
-docker compose -f .workflows/.dev/compose.yml logs -f api
+docker compose -f .workflows/dev/compose.yml logs -f api
 ```
 
 ### Stop services
 ```bash
 just dev down
 
 # Or with Docker Compose directly
-docker compose -f .workflows/.dev/compose.yml down
+docker compose -f .workflows/dev/compose.yml down
 ```
 
 ### Reset database
@@ -96,7 +96,7 @@ just dev reset
 
 ### Access running containers
 ```bash
-docker compose -f .workflows/.dev/compose.yml exec api bash
+docker compose -f .workflows/dev/compose.yml exec api bash
 ```
 
 ## How It Works
@@ -133,20 +133,20 @@ lsof -i :3000
 pnpm install
 
 # Restart containers to pick up changes
-docker compose -f .workflows/.dev/compose.yml restart api
+docker compose -f .workflows/dev/compose.yml restart api
 ```
 
 ### Database reset
 ```bash
 # Remove database volume (WARNING: deletes all data)
-docker compose -f .workflows/.dev/compose.yml down
+docker compose -f .workflows/dev/compose.yml down
 docker volume rm application_postgres_data
-docker compose -f .workflows/.dev/compose.yml up -d
+docker compose -f .workflows/dev/compose.yml up -d
 ```
 
 ### Clean slate
 ```bash
 # Remove all containers and volumes, then rebuild
-docker compose -f .workflows/.dev/compose.yml down -v
-docker compose -f .workflows/.dev/compose.yml up -d --build
+docker compose -f .workflows/dev/compose.yml down -v
+docker compose -f .workflows/dev/compose.yml up -d --build
 ```

.workflows/.dev/compose.tunnel.yml → .workflows/dev/compose.tunnel.yml

@@ -12,7 +12,7 @@
 #   2. Waits for cloudflared to print the *.trycloudflare.com URL
 #   3. Starts all remaining services with API_BASE_URL set to the tunnel URL
 #
-# The tunnel container does NOT depend on the API — cloudflared establishes
+# The tunnel container does NOT depend on the API - cloudflared establishes
 # the tunnel immediately and retries backend connections as needed.
 # ==============================================================================