Skip to main content

ARC // OS — Quick Start Guide (For Developers)

Audience: Developers setting up ARC // OS for local development

For user documentation, see USER_GUIDE.md.

Prerequisites​

  • Node.js LTS (v20+)
  • PostgreSQL (or Docker)
  • pnpm (⚠️ CRITICAL: This project uses pnpm exclusively. Do NOT use yarn or npm. Always use pnpm commands.)

Local Development Setup​

1. Database Setup​

Create a PostgreSQL database:

createdb arcos

Or use Docker:

docker run -d --name arcos_db -e POSTGRES_USER=arcos -e POSTGRES_PASSWORD=arcos_dev_password -e POSTGRES_DB=arcos -p 5432:5432 postgres:15-alpine

2. Backend Setup​

cd server

# Install dependencies
pnpm install

# Create .env file
cat > .env << EOF
DATABASE_URL="postgresql://arcos:arcos_dev_password@localhost:5432/arcos"
JWT_SECRET="dev-secret-change-in-production"
PORT=3001
NODE_ENV=development
EOF

# Generate Prisma client (MUST run after any schema changes)
pnpm prisma generate

# Run migrations (MUST run after any schema changes)
pnpm prisma migrate dev

# ⚠️ IMPORTANT: After ANY changes to server/prisma/schema.prisma:
# 1. Run: pnpm prisma migrate dev --name <migration_name>
# 2. Run: pnpm prisma generate
# The database schema MUST always be in sync with the Prisma schema model.

# Seed database (demo user + exercises - safe to run multiple times, prevents duplicates)
pnpm prisma db seed

# Start dev server
pnpm dev

3. Frontend Setup​

cd web

# Install dependencies
pnpm install

# Start dev server
pnpm dev

The app will be available at:

4. Login​

Use the demo credentials:

  • Email: demo@arcos.local
  • Password: demo123

Docker Setup​

# Build and start all services
docker compose up --build

# Run migrations
docker compose exec server pnpm prisma migrate deploy

# Seed database
docker compose exec server pnpm prisma db seed

Project Structure​

/server          Backend API (Fastify + Prisma)
  /prisma        Database schema and migrations
  /src
    /routes      API route handlers
    /services    Business logic
    /utils       Utilities (auth, logging, responses)
    /types       TypeScript types

/web             Frontend (React + Vite)
  /src
    /components  UI components (Button, Input, Card, etc.)
    /pages       Page components (Login, Week, Day, Settings, Grocery)
    /styles      CSS modules and design tokens
    /utils       API client and auth context

/docker          Dockerfiles and nginx config

Key Features​

✅ Daily Planner - Today, week, agenda, perimeter, timeboxes, Minimum Mode
✅ Training - Catalog, splits, sessions, mobility, cardio, PRs
✅ Nutrition - Meals, recipes, grocery, pantry, cooking rule
✅ Sleep & Recovery - Sleep, mood, energy, WHOOP import
✅ Brain - Notes, wikilinks, canvas, entity embeds
✅ Finance - Accounts, budgets, net worth, assets
✅ Social - People, happenings, groups, messaging
✅ Play - Idle Fighter, house, collections
✅ MCP - Claude connector at /mcp
✅ Public API - Write-only fitness API for subscribers

API Endpoints​

Prefer versioned paths (/api/v1/...). See API_DOCUMENTATION.md.

  • POST /api/v1/auth/register - Register new user
  • POST /api/v1/auth/login - Login
  • GET /api/v1/auth/me - Get current user
  • MCP: https://arcos.corgicy.com/mcp (OAuth)
  • Public API: /api/public/v1/... (API key, subscriber)

Testing​

# Backend tests
cd server
pnpm test

# Frontend tests
cd web
pnpm test

# Type checking
pnpm typecheck

Production Deployment​

  1. Set environment variables:

    • DATABASE_URL - Production PostgreSQL connection
    • JWT_SECRET - Strong random secret
    • NODE_ENV=production

  2. Run migrations:

    pnpm prisma migrate deploy

  3. Build and start:

    # Backend
    pnpm build
    pnpm start

    # Frontend
    pnpm build
    # Serve dist/ with nginx or similar

Architecture Notes​

  • Strong typing: TypeScript strict mode throughout
  • Validation: Zod schemas for all API inputs
  • Business logic: Lives in services, not in routes or Prisma
  • Response envelopes: Consistent { ok, data, error } format
  • Authentication: JWT in httpOnly cookies
  • UI: Monochrome design system with CSS Modules
  • Testing: Vitest for unit and integration tests

Next Steps​