Power Stack

A self-contained blueprint for reconstructing this monorepo stack from scratch.

---

1. Monorepo Layout

Bun workspaces. Root package.json declares "workspaces": ["apps/*", "packages/*"].

├── apps/
│   ├── api/            # REST backend (Bun + Elysia)
│   └── web/            # SPA frontend (React + Vite)
├── packages/
│   └── shared/         # Shared types, validators, permission utils
├── e2e/                # Playwright E2E test suite
├── openspec/           # Spec-driven change management
├── docker-compose.yml  # PostgreSQL + app + test containers
├── tsconfig.json       # Project references root
└── vitest.config.ts    # Multi-project test config

TypeScript project references: root tsconfig.json uses "files": [] + "references" to delegate to each workspace. Each workspace tsconfig has "composite": true. Type-check with tsc --build --noEmit.

---

2. Runtime & Language

• Bun 1.x as runtime and package manager (bun install, bun run)
• TypeScript 5.9 with strict mode, ESM everywhere ("type": "module")
• Target: ES2022, module resolution: bundler
• experimentalDecorators + emitDecoratorMetadata enabled for TypeORM

---

3. Environment Variables

Managed via .env at the project root (with .env.example checked in). Backend reads via process.env, frontend via Vite's VITE_ prefix.

Variable	Used by	Purpose	Default
POSTGRES_HOST	API	Database host	localhost
POSTGRES_PORT	API	Database port	16002
POSTGRES_USER	API	Database user	postgres
POSTGRES_PASSWORD	API	Database password	postgres
POSTGRES_DB	API	Database name	avant_id
API_PORT	API	HTTP listen port	16000
JWT_SECRET	API	Signing key for JWTs	dev fallback
WEB_URL	API	Frontend origin (CORS/redirects)	http://localhost:16001
NODE_ENV	API	Environment mode	development
VITE_API_URL	Web	API base URL for frontend	http://localhost:16000

---

4. Backend (apps/api)

Framework

Elysia 1.4 — lightweight Bun-native HTTP framework. Entry point imports reflect-metadata first, initializes TypeORM DataSource, then calls app.listen(port).

App composition via .use() plugin pattern:

new Elysia()
    .use(cors())
    .get('/health', () => ({ status: 'ok' }))
    .use(authRoutes)
    .use(adminRoutes);

Route groups use new Elysia({ prefix: '/auth' }) with request body validation via Elysia's t.Object() schema.

Error Handling

Use set.status pattern, not error():

async ({ body, set }) => {
    set.status = 400;
    return { error: 'Bad Request', message: 'Details' };
};

Auth Middleware

Elysia .derive() extracts Bearer token from Authorization header, verifies JWT via jose, and injects { user, auth } into context. .macro() defines requireAuth, requireAdmin, and requireAppPermission guards that check permissions and return 401/403.

Database

• PostgreSQL 17 via TypeORM 0.3 with DataSource config
• Connection from env vars: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
• synchronize: false always, schema changes via migrations only (packages/db/src/db/migrations/*.ts)
• Run migrations: bun run migrate (calls packages/db/src/db/migrate.ts)
• Generate migrations: bun run generate-migration (uses TypeORM CLI against packages/db/src/data-source.ts)

packages/db/src/db/migrate.ts:

import 'reflect-metadata';
import { AppDataSource } from './data-source';

async function runMigrations() {
    try {
        await AppDataSource.initialize();
        console.log('Running migrations...');
        await AppDataSource.runMigrations();
        console.log('Migrations completed successfully');
        await AppDataSource.destroy();
    } catch (error) {
        console.error('Migration failed:', error);
        process.exit(1);
    }
}

runMigrations();

• Entities: User (and domain-specific entities as needed)

Entity Conventions

• UUID primary keys (@PrimaryGeneratedColumn('uuid'))
• Explicit column types always (@Column({ type: 'text' }), @Column({ type: 'boolean' }))
• @CreateDateColumn({ type: 'timestamptz' }) / @UpdateDateColumn
• String-based relations to avoid circular imports: @OneToMany('UserPermission', 'user')
• Wrap relation types in Relation<T> from TypeORM

Auth Flow

• Password hashing: Argon2 via @node-rs/argon2
• JWT: jose library. Access tokens (short-lived) + refresh tokens (rotated, family-tracked for reuse detection). Revocation on reuse.

Route Groups

Prefix	Purpose
/auth	Register, login, logout, refresh, me, password reset, email verification
/admin	User management, app management (requires admin permission)

---

5. Frontend (apps/web)

Stack

• React 19 with react-dom/client (createRoot)
• MUI 7 + Emotion for styling
• React Router 7 (react-router-dom) with BrowserRouter
• Vite 7 as dev server and bundler (@vitejs/plugin-react)

App Structure

src/
├── main.tsx              # Entry: StrictMode > ThemeModeProvider > BrowserRouter > AuthProvider > App
├── App.tsx               # Route definitions
├── theme.ts              # MUI createTheme (dark-only, neon brutalist)
├── api/
│   ├── authFetch.ts      # Fetch wrapper with auto token refresh
│   └── admin.ts          # Admin API calls
├── context/
│   ├── AuthContext.tsx    # Auth state (login, register, logout, permissions)
│   └── ThemeContext.tsx   # Theme mode provider
├── pages/                # Route pages (Login, Register, Dashboard, admin/*)
└── components/           # Shared components (AdminRoute, Logo, etc.)

Auth Client Pattern

AuthContext stores JWT tokens in localStorage (accessToken, refreshToken, tokenExpiresAt). authFetch wraps fetch() to:

1. Proactively refresh if token expires within 60s
2. Add Authorization: Bearer header
3. Retry once on 401 after refresh
4. Dispatch auth:logout custom event on unrecoverable failure

Proactive refresh timer runs every 13 minutes. Visibility change handler refreshes on tab focus if token is near expiry.

Theme

Dark-only neon brutalist design: borderRadius: 0 everywhere, heavy borders (2-4px), box shadows offset to bottom-right (4px 4px 0 #000), hover transforms (translate(-2px, -2px)), uppercase headings/buttons with tight letter-spacing. Palette: deep navy backgrounds (#0f0f23, #1a1a2e), indigo primary (#6366f1), amber secondary (#f59e0b), neon green success (#00ff88), hot pink error (#ff3366).

Production

Vite builds static files. Served by nginx:alpine with a custom nginx.conf.

---

6. Shared Package (packages/shared)

Pure TypeScript, no runtime dependencies. Exports via subpath: . (root), ./types, ./utils. Contains shared types, interfaces, and utility functions used by both backend and frontend. Built with tsc to dist/.

---

7. Testing

Unit Tests

Vitest 4, configured as multi-project workspace in root vitest.config.ts. Three projects: shared, api, web. Each runs src/**/*.test.ts files. Run with bun run test.

E2E Tests

Playwright 1.58 in a dedicated e2e/ package. Three categories:

• *Api.spec.ts — API-only (no browser)
• *.spec.ts — UI tests (Chromium + mobile viewports)
• visual-*.spec.ts — Visual regression (baselines in e2e/tests/visual-baselines/)

Runs in Docker Compose with --profile testing: spins up PostgreSQL, API, web (nginx), runs migrations, then executes Playwright.

---

8. Docker

API Container

Multi-stage oven/bun:1 image:

1. deps — install workspace dependencies
2. build — copy source, build shared package
3. runner — copy built artifacts, run bun run src/index.ts directly (no compile step for API)

Web Container

Multi-stage build, final stage is nginx:alpine serving the Vite output from /usr/share/nginx/html.

Compose Services

Service	Image/Build	Purpose	Profile
postgres	postgres:17-alpine	Database	(default)
api	apps/api/Dockerfile	REST backend	apps, testing
web	apps/web/Dockerfile	Static frontend (nginx)	apps, testing
migrate-seed	(same as api)	Run migrations once	testing
e2e	e2e/Dockerfile	Playwright test runner	testing

Health checks on all services. E2E waits for postgres + api + web to be healthy before running.

---

9. CI/CD

Jenkins pipeline (Groovy Jenkinsfile):

1. Checkout — clean workspace, full clone
2. Install — bun install per workspace
3. Unit test — bun run test
4. E2E — Docker Compose up with testing profile, run Playwright, publish HTML report
5. Deploy — SSH to production server, git pull && docker compose --profile apps up -d --build

---

10. Code Quality

Tool	Config	Purpose
oxlint	oxlint .	Fast Rust-based linter
Prettier	prettier --write .	Code formatting
tsc --build	Project references mode	Type checking

---

11. OpenSpec

Spec-driven change management. Initialize with bunx openspec init. Structure:

openspec/
├── config.yaml    # Schema and project context
├── specs/         # Living specifications (one dir per feature)
└── changes/       # Change proposals and artifacts
    └── archive/   # Completed changes

Each feature has a spec.md describing its current state. Changes go through a structured workflow: proposal → artifacts (tasks, delta specs) → implementation → verification → archive. Specs are updated as changes land.

---

12. Key Dependencies Summary

Backend

Package	Purpose
elysia	HTTP framework
@elysiajs/cors	CORS middleware
typeorm	ORM (PostgreSQL)
pg	PostgreSQL driver
jose	JWT signing/verification
@node-rs/argon2	Password hashing
reflect-metadata	TypeORM decorator support

Frontend

Package	Purpose
react / react-dom	UI library
@mui/material	Component library
@emotion/react	CSS-in-JS (MUI peer dep)
@emotion/styled	Styled components
@mui/icons-material	Icon set
react-router-dom	Client routing
vite	Dev server + bundler

Dev Tooling

Package	Purpose
typescript	Type checking
vitest	Unit test framework
@playwright/test	E2E test framework
oxlint	Linting
prettier	Formatting
bun run --parallel	Parallel dev scripts (built-in)