Development Setup

Prerequisites

• Node.js 22+ (check with node -v)
• pnpm 10+ (enabled via corepack: corepack enable)
• MongoDB running locally or accessible remotely
• Git

Setup

1. Clone the repository

   git clone https://github.com/archmaxai/archmax.git
   cd archmax

2. Install dependencies

   pnpm install

3. Configure environment

   cp .env.example .env.local

   Edit .env.local with your MongoDB URI and other settings. See Configuration for all options.

4. Start development servers

   pnpm dev

   This starts all workspaces via Turborepo:

   • API: http://localhost:3000
   • Frontend: http://localhost:5173
   • Docs: http://localhost:4321

Monorepo Structure

archmax/
├── apps/
│   ├── api/          # Hono API server
│   ├── e2e/          # Playwright end-to-end tests
│   ├── frontend/     # React SPA (Vite + TanStack Router)
│   ├── worker/       # BullMQ worker for agent jobs
│   └── docs/         # Documentation site (Astro Starlight)
├── packages/
│   ├── core/         # Shared models, services, config (@archmax/core)
│   └── ui/           # React UI components (@archmax/ui)
├── openspec/         # Specifications and change proposals
└── turbo.json        # Turborepo pipeline config

Tech Stack

• TypeScript 5.9, strict mode, ESM-only
• Hono 4 for the API
• React 19 with Vite 6 for the frontend
• Mongoose 9 for MongoDB
• DuckDB for query federation
• Vitest for unit/integration testing
• Playwright for end-to-end testing

Running Tests

Unit and Integration Tests

pnpm test              # Run all tests
pnpm test --filter @archmax/core   # Run core package tests only

Tests are colocated with source files (e.g., my-service.ts has my-service.test.ts alongside it).

E2E Tests (Playwright)

End-to-end tests run Playwright against the full Docker image with federated database services. They live in apps/e2e/.

The docker-compose.ci.yml starts the app image alongside MongoDB, Redis, PostgreSQL, MySQL, Microsoft SQL Server, and a mounted SQLite fixture file. This is the same stack that CI uses on every pull request.

# Build (or pull) the app image
docker build -t archmax:local .

# Start the full stack
APP_IMAGE=archmax:local docker compose -f docker-compose.ci.yml up -d

# Wait for health (may take 1-2 minutes while MSSQL boots)
curl --retry 30 --retry-delay 5 --retry-connrefused http://localhost:8080/api/health

# Install Playwright browsers (first time only)
pnpm --filter @archmax/e2e exec playwright install --with-deps chromium

# Run the tests
pnpm --filter @archmax/e2e test

# Tear down
docker compose -f docker-compose.ci.yml down -v

Default credentials are admin / testpass123. To override, set UI_USERNAME / UI_PASSWORD as environment variables for compose and E2E_USERNAME / E2E_PASSWORD for the Playwright test runner.

MSSQL note: The SQL Server container (mcr.microsoft.com/mssql/server:2022-latest) requires at least 2 GB RAM and only runs on linux/amd64. On Apple Silicon Macs, Docker Desktop runs it under Rosetta emulation, which is slower to start. The compose file pins platform: linux/amd64 for this service.

In CI, E2E tests run automatically after the Docker image is built on every pull request.

Building

pnpm build             # Build all workspaces
pnpm typecheck         # Type-check all workspaces

Code Conventions

• Strict TypeScript (strict: true) everywhere
• Functional React components only
• cn() utility for Tailwind class composition
• No comments that narrate what the code does
• CVA for component variants in @archmax/ui