diff --git a/README.md b/README.md index d861aa2..f2dd043 100644 --- a/README.md +++ b/README.md @@ -3,112 +3,258 @@

CapaKraken

+

- Resource & Capacity Planning for 3D Production Studios -

-

- Plan teams. Track chargeability. Forecast budgets. Staff smarter. + Resource & Capacity Planning for 3D Production Studios
+ Plan teams. Track chargeability. Forecast budgets. Staff smarter.

TypeScript Next.js 15 - PostgreSQL - tRPC + React 19 + PostgreSQL 16 + tRPC v11 Prisma - Tailwind CSS + Tailwind CSS v4 + Docker License

--- -## What is CapaKraken? +## About -CapaKraken is a full-stack resource planning and project staffing tool built for 3D production environments (VFX, animation, automotive visualization). It replaces spreadsheet-based capacity planning with a real-time, multi-user web application. +CapaKraken is a full-stack resource planning and project staffing application built for 3D production environments -- VFX studios, animation houses, and automotive visualization teams. It replaces spreadsheet-based capacity planning with a real-time, multi-user web application that provides a single source of truth for who is working on what, when, and at what cost. -### Key Capabilities - -- **Interactive Timeline** -- Drag-and-drop resource allocation across projects with day/week/month zoom, sub-lane stacking, heatmap overlays, and vacation integration -- **Chargeability Forecasting** -- Monthly chargeability reports with target comparison, drill-down grouping, holiday-aware SAH calculations, and Excel/CSV export -- **Budget & Cost Tracking** -- Real-time budget burn rate, daily cost projections, and cost-per-allocation tracking with currency support (cents-based precision) -- **Estimating System** -- Full CRUD estimate workspaces with versioning, approval workflows, planning handoff, rate cards per client, experience multipliers, and shoring ratios -- **Staffing & Demand** -- Open demand tracking, AI-assisted profile matching, skill gap analysis, and demand-to-assignment conversion -- **Scenario Planning** -- What-if scenarios for allocation changes with baseline comparison and simulation -- **Customizable Dashboards** -- Widget-based dashboards with drag-and-drop layout, 10+ widget types, and per-user preferences -- **Blueprint System** -- Dynamic custom fields on projects and resources via admin-defined blueprints -- **Role & Skill Management** -- Hierarchical roles, management levels, skill matrices, and competency tracking -- **Multi-tenant Client Hierarchy** -- Nested client/chapter structure with project assignment and chargeability scoping +The application was designed from the ground up for the unique challenges of creative production: fluctuating team sizes, overlapping project phases, mixed chargeability models (client-billable vs. internal vs. BD), complex holiday calendars across multiple countries, and the need to forecast resource availability months in advance. --- -## Screenshots +## Feature Overview - - - - - - - - - - - - - -
- Timeline - Resource View
- Timeline with resource allocations, vacation overlays, and weekend highlighting - 		- Chargeability Report
- Chargeability forecast with monthly breakdown and holiday deduction rules -
- Allocations
- Allocation management with status badges, project grouping, and inline editing - 		- Dashboard Widgets
- Customizable dashboard with widget catalog and drag-and-drop layout -
- Admin - Clients
- Client hierarchy management with drag-and-drop reordering - 		- Chargeability Overview
- Chargeability overview with per-resource utilization heatmap -
+### Interactive Timeline + +

+ Timeline - Resource View +

+ +The timeline is the centerpiece of CapaKraken. It provides a visual, interactive view of all resource allocations across projects. + +- **Resource View** -- see all allocations for each person, with color-coded project bars stacked in sub-lanes when they overlap +- **Project View** -- flip the perspective to see all resources assigned to each project +- **Zoom Levels** -- switch between day, week, and month granularity; the grid adapts automatically +- **Drag-and-Drop** -- click and drag on empty timeline cells to create new allocations; existing bars can be moved or resized +- **Heatmap Overlay** -- toggle a per-day utilization heatmap that colors cells from green (underbooked) through yellow to red (overbooked), with configurable color schemes +- **Vacation Integration** -- approved and pending vacations overlay as semi-transparent bars; public holidays are shown per-country with federal state and city awareness +- **Weekend Highlighting** -- weekend columns follow the configurable accent/brand color for instant visual orientation +- **Filters** -- filter by project, client, chapter, country, role, order type, and more; toggle visibility of completed/cancelled projects, draft projects, and vacation blocks +- **Overbooking Detection** -- days where a resource exceeds their available hours flash with a warning overlay + +### Chargeability Forecasting + +

+ Chargeability Report +

+ +The chargeability module provides monthly forecasts comparing actual allocation against targets. + +- **Standard Available Hours (SAH)** -- automatically calculated per resource, per month, accounting for weekends, public holidays (country/state/city-level), annual leave, sick days, and custom deductions +- **Holiday Deduction Rules** -- configurable per location: which holiday types to deduct, which calendars to apply, with a visual breakdown of gross days, holiday counts, and resulting net working days +- **Target Comparison** -- set chargeability targets at group or individual level; the report shows actual vs. target with color-coded variance +- **Drill-Down Grouping** -- group by chapter, role, management level, country, or custom dimensions +- **Active Filters** -- same powerful filter set as the timeline, applied consistently +- **Export** -- one-click Excel and CSV export with all visible data, formatting preserved + +### Chargeability Overview + +

+ Chargeability Overview +

+ +A high-level view showing per-resource utilization as a color-coded heatmap across months, making it easy to spot under- or over-utilized team members at a glance. + +### Allocations + +

+ Allocations +

+ +A structured list view of all allocations with: + +- **Status Workflow** -- allocations move through Proposed, Confirmed, Active, Completed, and Cancelled states +- **Grouping** -- view by resource or by project, with expandable/collapsible groups +- **Inline Editing** -- quick-edit hours, dates, and status directly from the list +- **Bulk Operations** -- multi-select allocations for batch status changes or deletion +- **Data Density Toggle** -- switch between compact and detailed views; hide/show metadata columns +- **New Planning Entry** -- create allocations from a floating action button with project and resource pickers + +### Customizable Dashboards + +

+ Dashboard Widgets +

+ +Each user gets a personal dashboard they can customize with drag-and-drop widgets: + +| Widget | Description | +|--------|-------------| +| **Overview Stats** | Total resources, active projects, allocations, and budget utilization at a glance | +| **My Projects** | Quick access to projects where the current user is assigned or responsible | +| **Resource Table** | Filterable EID list with utilization percentages and chargeability indicators | +| **Project Overview** | All projects with cost, person days, and status badges | +| **Peak Times** | Bar chart showing booked hours vs. capacity over time, with department breakdown | +| **Demand View** | Staffing demand vs. supply by project, with unfilled headcount tracking | +| **Chargeability Overview** | Leaderboard of resources ranked by chargeability score | +| **Budget Forecast** | Budget burn rate and projected cost per active project | +| **Skill Gap Analysis** | Top skill shortages comparing open demand against available supply | +| **Project Health** | Composite health score per project (budget, staffing, timeline) | + +Widgets are resizable, and the layout persists per user. An **Add Widget** catalog lets users browse available widgets with descriptions and default sizes. + +### Estimating System + +A full project estimation workflow: + +- **Estimate Workspaces** -- create, version, and compare estimates with full CRUD +- **Scope Items** -- break down deliverables into line items with assumptions and constraints +- **Demand Lines** -- define required roles, hours, and rates per scope item +- **Rate Cards** -- client-specific rate cards with experience multipliers and shoring ratios (onshore/nearshore/offshore) +- **Version Control** -- save snapshots, compare versions side-by-side, and track what changed +- **Approval Workflow** -- submit estimates for approval; approved versions can be handed off to create actual project allocations +- **Planning Handoff** -- one-click conversion from approved estimate to live project allocations with resource assignment + +### Staffing & Demand Management + +- **Open Demand Tracking** -- projects can declare required roles and headcount; unfilled positions show as dashed bars on the timeline +- **AI-Assisted Matching** -- when filling demand, the system suggests best-fit resources based on skills, availability, cost, and location +- **Skill Gap Analysis** -- dashboard widget comparing aggregate demand against available supply, highlighting bottleneck roles +- **Demand-to-Assignment** -- convert demand entries into confirmed allocations with a guided workflow + +### Scenario Planning + +- **What-If Scenarios** -- create sandbox copies of the current allocation state +- **Simulation** -- add, move, or remove allocations in the scenario without affecting production data +- **Baseline Comparison** -- see what changed between the scenario and the current baseline +- **Apply or Discard** -- promote a scenario to production or delete it + +### Admin & Configuration + +

+ Admin - Clients +

+ +- **Client Hierarchy** -- nested client/chapter/sub-chapter tree with drag-and-drop reordering; clients scope chargeability and project assignment +- **Blueprints** -- define custom field schemas (text, number, select, date, etc.) that attach to projects or resources; field values are validated, searchable, and filterable +- **Roles & Management Levels** -- hierarchical role tree with cost rates; management levels for organizational reporting +- **Rate Cards** -- global and per-client rate tables with currency support +- **Vacations & Holidays** -- manage public holiday calendars per country/state/city; approve/reject leave requests; import calendars from external sources +- **Calculation Rules** -- configure SAH parameters, chargeability targets, and deduction policies +- **Users & Auth** -- invite users by email, Argon2 password hashing, optional TOTP two-factor authentication, role-based access control (Admin, Manager, Viewer, User) +- **Settings** -- SMTP configuration (also configurable via env vars), notification preferences, accent color theme +- **Broadcasts** -- send system-wide announcements to all users +- **Webhooks** -- configure outgoing webhook notifications for key events +- **Activity Log** -- audit trail of significant actions across the system + +### Real-Time Collaboration + +- **Server-Sent Events (SSE)** -- allocation changes, project updates, and notifications are pushed to all connected clients in real time via Redis pub/sub +- **Notification Center** -- in-app notification bell with unread count, grouped by category, with click-to-navigate +- **Optimistic Updates** -- UI reflects changes immediately while the server confirms in the background + +### Theming + +- **Dark Mode** -- full dark theme with CSS variable-based surface system; all components adapt automatically +- **Accent Colors** -- choose from multiple accent color presets (Sky, Indigo, Emerald, Rose, Amber, Violet) that flow through the entire UI: buttons, links, timeline highlights, charts, and badges +- **Responsive Layout** -- collapsible sidebar, adaptive grid layouts, mobile-aware touch interactions --- ## Tech Stack -| Layer | Technology | -|-------|-----------| -| **Frontend** | Next.js 15 (App Router), React 19, Tailwind CSS v4 | -| **API** | tRPC v11 (end-to-end type safety) | -| **Database** | PostgreSQL 16 via Prisma ORM | -| **Auth** | Auth.js v5 with Argon2 password hashing, TOTP MFA | -| **Realtime** | Server-Sent Events (SSE) with Redis pub/sub | -| **Monorepo** | pnpm workspaces + Turborepo | -| **Testing** | Vitest (unit), Playwright (E2E) | -| **Containerization** | Docker Compose (dev + prod) | +| Layer | Technology | Purpose | +|-------|-----------|---------| +| **Frontend** | Next.js 15 (App Router), React 19 | Server components, streaming, file-based routing | +| **Styling** | Tailwind CSS v4 | Utility-first CSS with custom design tokens | +| **API** | tRPC v11 | End-to-end type-safe RPC between client and server | +| **Database** | PostgreSQL 16 via Prisma ORM | Relational data with JSONB for dynamic fields | +| **Auth** | Auth.js v5 | Session management, Argon2 passwords, TOTP MFA | +| **Realtime** | SSE + Redis pub/sub | Live updates without WebSocket complexity | +| **AI** | Azure OpenAI / Gemini | Staffing suggestions, skill profile generation | +| **Monorepo** | pnpm workspaces + Turborepo | Incremental builds, shared configs, dependency isolation | +| **Testing** | Vitest + Playwright | Unit tests (engine, shared) and E2E browser tests | +| **Containerization** | Docker Compose | Dev and production stacks with health checks | ### Monorepo Structure ``` capakraken/ -├── apps/web/ # Next.js frontend + API routes -├── packages/ -│ ├── shared/ # Types, schemas, constants shared across packages -│ ├── db/ # Prisma schema, migrations, seed scripts -│ ├── engine/ # Pure calculation logic (SAH, chargeability, budget) -│ ├── staffing/ # AI-assisted staffing and capacity analysis -│ ├── application/ # Use-case layer (business logic orchestration) -│ ├── api/ # tRPC routers and procedures -│ └── ui/ # Shared UI components (planned) -└── tooling/ - ├── docker/ # Dev container entrypoint scripts - ├── deploy/ # Production deployment scripts - ├── eslint/ # Shared ESLint config - └── typescript/ # Shared tsconfig bases +| ++-- apps/ +| +-- web/ Next.js 15 application (frontend + API routes) +| +-- src/ +| +-- app/ App Router pages and layouts +| +-- components/ React components organized by domain +| +-- hooks/ Custom React hooks +| +-- lib/ Client utilities, formatters, constants +| +-- server/ Server-side auth, tRPC context +| ++-- packages/ +| +-- shared/ Types, Zod schemas, constants (zero dependencies) +| +-- db/ Prisma schema, migrations, seed scripts +| +-- engine/ Pure calculation logic (SAH, chargeability, budget, allocation) +| +-- staffing/ AI-assisted staffing, capacity analysis, profile matching +| +-- application/ Use-case orchestration layer (business workflows) +| +-- api/ tRPC routers, procedures, middleware +| +-- ui/ Shared UI component library (planned) +| ++-- tooling/ +| +-- docker/ Container entrypoint scripts +| +-- deploy/ Production deployment automation +| +-- eslint/ Shared ESLint configuration +| +-- typescript/ Shared tsconfig bases +| ++-- scripts/ Lifecycle scripts (start, stop, DB management) ++-- docs/ Product docs, architecture decisions, screenshots +``` + +### Architecture + +``` ++---------------------------------------------------------------+ +| Browser (React 19) | +| Dashboard | Timeline | Allocations | Chargeability | ++------+-----+-----+------+-------+-------+--------+-----------+ + | | | | + | tRPC (type-safe RPC over HTTP) | + | | | | ++------+-----------+---------------+----------------+-----------+ +| Next.js 15 App Router | +| (Server Components + API Routes) | ++------+-----+-----+------+-------+-------+--------+-----------+ + | | | | ++------+-----------+---------------+----------------+-----------+ +| packages/api (tRPC v11) | +| allocation.* | project.* | chargeability.* | estimate.*| ++------+-----+---+-----+------+-------+-----------+-----------+ + | | | | ++------+-----------+-------+ +----+----------------+-----------+ +| packages/application | | packages/engine | +| (use-case orchestration) | | (pure calculations, no I/O) | +| - estimate workflows | | - SAH calculator | +| - dashboard aggregation | | - chargeability engine | +| - staffing use-cases | | - budget monitor | ++------+-------------------+ | - allocation calculator | + | +----+----------------------------+ + | | ++------+---------------------------+----------------------------+ +| packages/db (Prisma ORM) | +| schema.prisma | migrations | seed | queries | ++------+-------------------------------------------------------+ + | ++------+-------------------------------------------------------+ +| PostgreSQL 16 + Redis 7 | ++---------------------------------------------------------------+ ``` --- @@ -117,19 +263,23 @@ capakraken/ ### Prerequisites -| Requirement | Minimum Version | -|-------------|----------------| -| **Node.js** | 20.x | -| **pnpm** | 9.x | -| **Docker** + **Docker Compose** | Docker 24+, Compose v2 | +| Requirement | Minimum Version | Check | +|-------------|----------------|-------| +| **Node.js** | 20.x | `node --version` | +| **pnpm** | 9.x | `pnpm --version` | +| **Docker** | 24+ | `docker --version` | +| **Docker Compose** | v2 | `docker compose version` | ### 1. Clone and configure ```bash -git clone capakraken +git clone https://gitea.hartmut-noerenberg.com/Hartmut/plANARCHY.git capakraken cd capakraken +``` -# Create your environment file from the template +Create your environment file: + +```bash cp .env.example .env ``` @@ -137,64 +287,98 @@ Edit `.env` and fill in the required values: ```bash # Required -- generate with: openssl rand -base64 32 -NEXTAUTH_SECRET= +NEXTAUTH_SECRET= -# Required -- your app URL (use http://localhost:3100 for local dev) +# Required -- your app URL NEXTAUTH_URL=http://localhost:3100 -# Required for pgAdmin (any password) +# Required for the pgAdmin web UI PGADMIN_PASSWORD=admin ``` -The database connection, Redis, and SMTP are pre-configured for Docker Compose and work out of the box. +> **Note:** The database connection (`DATABASE_URL`), Redis, and SMTP (MailHog) are pre-configured for Docker Compose and work out of the box. See [`.env.example`](.env.example) for the full reference with all optional variables. ### 2. Start with Docker (recommended) ```bash -# Start everything (PostgreSQL, Redis, MailHog, app) bash scripts/start.sh ``` -This will: -1. Start PostgreSQL and Redis containers -2. Build the app container (first run takes a few minutes) -3. Run Prisma migrations automatically -4. Start the Next.js dev server +This single command will: -Once ready, open **http://localhost:3100** in your browser. +1. Pull and start **PostgreSQL 16** and **Redis 7** containers +2. Build the application Docker image (first run: ~2 minutes) +3. Run **Prisma migrations** automatically against the database +4. Validate workspace exports and imports +5. Start the **Next.js dev server** with hot reload on port 3100 + +You'll see output like: + +``` +Starting CapaKraken... + Starting PostgreSQL + Redis... + Waiting for PostgreSQL... + Starting app container on port 3100... + Waiting for server (up to 90s)... + +CapaKraken is running! +{ + "status": "ok", + "database": "connected", + "redis": "connected" +} + + URL: http://localhost:3100 +``` ### 3. Start without Docker (host-native) +If you prefer running Node.js directly on your machine: + ```bash -# Install dependencies +# Install all workspace dependencies pnpm install -# Start PostgreSQL and Redis (still via Docker) +# Start only the infrastructure via Docker docker compose up -d postgres redis -# Generate Prisma client and run migrations +# Generate the Prisma client and apply migrations pnpm db:generate pnpm db:migrate -# Start the dev server +# Start the Next.js dev server with hot reload pnpm dev ``` ### 4. Create your first user -On the login page, click **Sign up** to create an admin account. The first user is automatically granted admin privileges. +1. Open **http://localhost:3100** in your browser +2. Click **Sign up** on the login page +3. Enter your name, email, and password +4. The first registered user is automatically granted **Admin** privileges +5. Explore the sidebar to discover all features + +### 5. Load demo data (optional) + +```bash +pnpm db:seed +``` + +This populates the database with sample clients, projects, resources, allocations, and roles so you can immediately explore all features without manual setup. --- ## Available Services -| Service | URL | Description | -|---------|-----|-------------| -| **App** | http://localhost:3100 | Main application | -| **MailHog** | http://localhost:8025 | Email testing UI (catches all outgoing mail) | -| **pgAdmin** | http://localhost:5050 | Database administration | -| **PostgreSQL** | localhost:5433 | Direct database access | -| **Redis** | localhost:6380 | Cache and pub/sub | +When running with Docker Compose, the following services are available: + +| Service | URL | Purpose | +|---------|-----|---------| +| **CapaKraken App** | [localhost:3100](http://localhost:3100) | Main application | +| **MailHog** | [localhost:8025](http://localhost:8025) | Email testing UI -- catches all outgoing emails (invitations, password resets, notifications) | +| **pgAdmin** | [localhost:5050](http://localhost:5050) | Visual database administration | +| **PostgreSQL** | `localhost:5433` | Direct database access (user: `capakraken`, db: `capakraken`) | +| **Redis** | `localhost:6380` | Cache, rate limiting, and SSE pub/sub | --- @@ -202,119 +386,120 @@ On the login page, click **Sign up** to create an admin account. The first user ### Application Lifecycle -```bash -bash scripts/start.sh # Start all services -bash scripts/stop.sh # Stop all services -bash scripts/restart.sh # Stop + start -``` +| Command | Description | +|---------|-------------| +| `bash scripts/start.sh` | Start all services (PostgreSQL, Redis, app) | +| `bash scripts/stop.sh` | Stop all services gracefully | +| `bash scripts/restart.sh` | Full stop + start cycle | ### Development -```bash -pnpm dev # Start Next.js dev server (host-native) -pnpm build # Production build -pnpm lint # ESLint across all packages -pnpm test:unit # Run unit tests (Vitest) -pnpm test:e2e # Run E2E tests (Playwright) -``` +| Command | Description | +|---------|-------------| +| `pnpm dev` | Start Next.js dev server with hot reload (host-native) | +| `pnpm build` | Production build (standalone output) | +| `pnpm lint` | Run ESLint across all packages | +| `pnpm format` | Format all files with Prettier | +| `pnpm test:unit` | Run unit tests via Vitest | +| `pnpm test:e2e` | Run end-to-end tests via Playwright | +| `pnpm typecheck` | TypeScript type checking across all packages | +| `pnpm check:architecture` | Verify architecture guardrails (import boundaries, etc.) | ### Database -```bash -pnpm db:generate # Regenerate Prisma client -pnpm db:migrate # Create and apply migrations -pnpm db:push # Push schema changes (no migration file) -pnpm db:studio # Open Prisma Studio -pnpm db:seed # Seed demo data -pnpm db:doctor # Health check on database state -``` - -### Quality Gates - -```bash -pnpm test:unit # Unit tests -pnpm --filter @capakraken/web exec tsc --noEmit # Type check -pnpm lint # Linting -pnpm check:architecture # Architecture guardrails -``` +| Command | Description | +|---------|-------------| +| `pnpm db:generate` | Regenerate Prisma client after schema changes | +| `pnpm db:migrate` | Create and apply new migrations | +| `pnpm db:push` | Push schema changes directly (no migration file) | +| `pnpm db:studio` | Open Prisma Studio (visual data browser) | +| `pnpm db:seed` | Seed the database with demo data | +| `pnpm db:doctor` | Run health checks on database state | +| `pnpm db:seed:export` | Export current DB state as a seed file | +| `pnpm db:seed:import` | Import a previously exported seed file | --- ## Production Deployment -CapaKraken ships with a Docker Compose production stack (`docker-compose.prod.yml`) and a deployment script: +CapaKraken ships with a production-ready Docker Compose stack and deployment automation. + +### Quick Deploy ```bash -# Set required environment variables +# Configure required secrets export APP_IMAGE=ghcr.io/your-org/capakraken-app:latest export MIGRATOR_IMAGE=ghcr.io/your-org/capakraken-migrator:latest -export POSTGRES_PASSWORD= +export POSTGRES_PASSWORD=$(openssl rand -hex 32) +export REDIS_PASSWORD=$(openssl rand -hex 32) +export NEXTAUTH_SECRET=$(openssl rand -base64 32) -# Deploy +# Deploy with readiness verification bash tooling/deploy/deploy-compose.sh production ``` -The production stack includes: -- Multi-stage Docker build with standalone Next.js output -- Automatic database migrations via a sidecar migrator container -- Redis with password authentication -- Health check and readiness probe at `/api/ready` -- Configurable via environment files (`.env.production`, `deploy.env`) +### Production Stack Features + +- **Multi-stage Docker build** -- optimized standalone Next.js output (~150 MB image) +- **Sidecar migrator** -- runs Prisma migrations before the app starts, then exits +- **Redis authentication** -- password-protected with `--requirepass` +- **Health probes** -- `/api/health` (liveness) and `/api/ready` (readiness with DB + Redis checks) +- **Automatic rollback** -- deployment script verifies readiness; on failure, logs are captured for debugging +- **Environment separation** -- configure via `.env.production` and `deploy.env` files +- **Container registry** -- configurable via `DOCKER_REGISTRY` (defaults to `ghcr.io`) --- ## Environment Variables -See [`.env.example`](.env.example) for the full reference with descriptions. Key variables: +See [`.env.example`](.env.example) for the complete reference with inline documentation. Summary of key variables: -| Variable | Required | Description | -|----------|----------|-------------| -| `NEXTAUTH_URL` | Yes | Public app URL | -| `NEXTAUTH_SECRET` | Yes | JWT signing secret | -| `DATABASE_URL` | Yes | PostgreSQL connection string | -| `REDIS_PASSWORD` | Prod | Redis authentication | -| `SMTP_HOST` | No | Email delivery (optional, configurable via Admin UI) | -| `AZURE_OPENAI_API_KEY` | No | AI-assisted staffing features | -| `GEMINI_API_KEY` | No | Alternative AI provider | +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `NEXTAUTH_URL` | Yes | -- | Public URL of the application | +| `NEXTAUTH_SECRET` | Yes | -- | Secret for JWT signing and session encryption | +| `DATABASE_URL` | Yes | `localhost:5433` | PostgreSQL connection string | +| `REDIS_PASSWORD` | Prod | -- | Redis authentication password | +| `REDIS_URL` | No | `redis://redis:6379` | Redis connection (auto-configured in Docker) | +| `SMTP_HOST` | No | -- | SMTP server for email delivery | +| `SMTP_PORT` | No | `587` | SMTP port | +| `SMTP_FROM` | No | `noreply@capakraken.dev` | Sender address for outgoing emails | +| `AZURE_OPENAI_API_KEY` | No | -- | Enables AI-assisted staffing features | +| `GEMINI_API_KEY` | No | -- | Alternative AI provider | +| `LOG_LEVEL` | No | `info` | Logging verbosity (trace/debug/info/warn/error) | +| `CRON_SECRET` | No | -- | Authenticates scheduled job endpoints | --- -## Project Structure Highlights +## Design Principles -### Layers - -The codebase follows a clean layered architecture: - -``` -UI (apps/web) - ↓ tRPC calls -API (packages/api) - ↓ orchestrates -Application (packages/application) - ↓ delegates to -Engine (packages/engine) -- pure calculations, no I/O -Staffing (packages/staffing) -- AI-assisted matching -DB (packages/db) -- Prisma schema and data access -Shared (packages/shared) -- types, schemas, constants -``` - -### Design Principles - -- **Money as integer cents** -- all monetary values stored and calculated in cents to avoid floating-point drift -- **Strict TypeScript** -- no `any`, strict null checks, explicit Prisma casts at package boundaries -- **Domain-driven packaging** -- each bounded context (estimating, chargeability, staffing) lives in its own package -- **Real-time by default** -- SSE pushes allocation and project changes to all connected clients via Redis pub/sub -- **Theme-aware UI** -- configurable accent color system with full dark mode support +| Principle | Implementation | +|-----------|---------------| +| **Money as integer cents** | All monetary values stored and calculated in cents to eliminate floating-point drift | +| **Strict TypeScript** | No `any` types, strict null checks, explicit Prisma casts at package boundaries | +| **Domain-driven packages** | Each bounded context (estimating, chargeability, staffing) lives in its own package with clear exports | +| **Pure engine logic** | Calculation packages have zero I/O dependencies -- they take data in and return results | +| **Real-time by default** | SSE pushes changes to all clients via Redis pub/sub; no polling | +| **Theme-aware UI** | CSS variable-based surface system with configurable accent colors and full dark mode | +| **Defensive data handling** | Nullable foreign keys handled explicitly; Prisma enums and JSONB cast at boundaries | +| **No speculative abstractions** | Build what's needed now; three similar lines beat a premature abstraction | --- ## Contributing 1. Create a feature branch from `main` -2. Follow the existing code style (ESLint + Prettier enforce it) -3. Add tests for new business logic (especially in `packages/engine`) -4. Ensure all quality gates pass before opening a PR -5. Keep commits focused and well-described +2. Follow the existing code style -- ESLint and Prettier enforce it automatically +3. Add unit tests for new business logic, especially in `packages/engine` +4. Run quality gates before submitting: + ```bash + pnpm test:unit + pnpm --filter @capakraken/web exec tsc --noEmit + pnpm lint + pnpm check:architecture + ``` +5. Keep commits focused with descriptive messages +6. Open a pull request with a clear description of what changed and why ---