Hartmut/CapaKraken
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: enhance README with detailed feature descriptions and architecture diagram

Browse Source 
- Add per-feature deep-dive sections with screenshots and bullet-point details
- Add widget catalog table listing all 10 dashboard widget types
- Add ASCII architecture diagram showing package layering
- Expand monorepo structure with subdirectory explanations
- Add design principles table
- Expand getting started guide with demo data instructions
- Add production deployment details (multi-stage build, health probes, rollback)
- Expand environment variables table with defaults
- Expand scripts reference to table format with all available commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Hartmut Nörenberg
2026-04-10 14:10:15 +02:00
parent 600a86ca71
commit 605fd7cea1
1 changed files with 371 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+371 -186
View File
@@ -3,112 +3,258 @@
</p> </p>
<h1 align="center">CapaKraken</h1> <h1 align="center">CapaKraken</h1>
<p align="center"> <p align="center">
<strong>Resource &amp; Capacity Planning for 3D Production Studios</strong> <strong>Resource &amp; Capacity Planning for 3D Production Studios</strong><br/>
</p> <sub>Plan teams. Track chargeability. Forecast budgets. Staff smarter.</sub>
<p align="center">
<em>Plan teams. Track chargeability. Forecast budgets. Staff smarter.</em>
</p> </p>
<p align="center"> <p align="center">
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white" /> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white" />
<img alt="Next.js 15" src="https://img.shields.io/badge/Next.js-15-black?logo=nextdotjs&logoColor=white" /> <img alt="Next.js 15" src="https://img.shields.io/badge/Next.js-15-black?logo=nextdotjs&logoColor=white" />
<img alt="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-16-336791?logo=postgresql&logoColor=white" /> <img alt="React 19" src="https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=black" />
<img alt="tRPC" src="https://img.shields.io/badge/tRPC-v11-2596BE?logo=trpc&logoColor=white" /> <img alt="PostgreSQL 16" src="https://img.shields.io/badge/PostgreSQL-16-336791?logo=postgresql&logoColor=white" />
<img alt="tRPC v11" src="https://img.shields.io/badge/tRPC-v11-2596BE?logo=trpc&logoColor=white" />
<img alt="Prisma" src="https://img.shields.io/badge/Prisma-ORM-2D3748?logo=prisma&logoColor=white" /> <img alt="Prisma" src="https://img.shields.io/badge/Prisma-ORM-2D3748?logo=prisma&logoColor=white" />
<img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind-v4-38bdf8?logo=tailwindcss&logoColor=white" /> <img alt="Tailwind CSS v4" src="https://img.shields.io/badge/Tailwind-v4-38bdf8?logo=tailwindcss&logoColor=white" />
<img alt="Docker" src="https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white" />
<img alt="License" src="https://img.shields.io/badge/License-Proprietary-red" /> <img alt="License" src="https://img.shields.io/badge/License-Proprietary-red" />
</p> </p>
--- ---
## 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 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.
- **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
--- ---
## Screenshots ## Feature Overview
<table> ### Interactive Timeline
<tr>
<td width="50%"> <p align="center">
<img src="docs/screenshots/timeline-resource-dark.jpeg" alt="Timeline - Resource View" /><br /> <img src="docs/screenshots/timeline-resource-dark.jpeg" alt="Timeline - Resource View" width="100%" />
<em>Timeline with resource allocations, vacation overlays, and weekend highlighting</em> </p>
</td>
<td width="50%"> The timeline is the centerpiece of CapaKraken. It provides a visual, interactive view of all resource allocations across projects.
<img src="docs/screenshots/chargeability-detail-dark.jpeg" alt="Chargeability Report" /><br />
<em>Chargeability forecast with monthly breakdown and holiday deduction rules</em> - **Resource View** -- see all allocations for each person, with color-coded project bars stacked in sub-lanes when they overlap
</td> - **Project View** -- flip the perspective to see all resources assigned to each project
</tr> - **Zoom Levels** -- switch between day, week, and month granularity; the grid adapts automatically
<tr> - **Drag-and-Drop** -- click and drag on empty timeline cells to create new allocations; existing bars can be moved or resized
<td width="50%"> - **Heatmap Overlay** -- toggle a per-day utilization heatmap that colors cells from green (underbooked) through yellow to red (overbooked), with configurable color schemes
<img src="docs/screenshots/allocations-dark.jpeg" alt="Allocations" /><br /> - **Vacation Integration** -- approved and pending vacations overlay as semi-transparent bars; public holidays are shown per-country with federal state and city awareness
<em>Allocation management with status badges, project grouping, and inline editing</em> - **Weekend Highlighting** -- weekend columns follow the configurable accent/brand color for instant visual orientation
</td> - **Filters** -- filter by project, client, chapter, country, role, order type, and more; toggle visibility of completed/cancelled projects, draft projects, and vacation blocks
<td width="50%"> - **Overbooking Detection** -- days where a resource exceeds their available hours flash with a warning overlay
<img src="docs/screenshots/dashboard-widgets-dark.jpeg" alt="Dashboard Widgets" /><br />
<em>Customizable dashboard with widget catalog and drag-and-drop layout</em> ### Chargeability Forecasting
</td>
</tr> <p align="center">
<tr> <img src="docs/screenshots/chargeability-detail-dark.jpeg" alt="Chargeability Report" width="100%" />
<td width="50%"> </p>
<img src="docs/screenshots/admin-clients-dark.jpeg" alt="Admin - Clients" /><br />
<em>Client hierarchy management with drag-and-drop reordering</em> The chargeability module provides monthly forecasts comparing actual allocation against targets.
</td>
<td width="50%"> - **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
<img src="docs/screenshots/chargeability-dark.jpeg" alt="Chargeability Overview" /><br /> - **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
<em>Chargeability overview with per-resource utilization heatmap</em> - **Target Comparison** -- set chargeability targets at group or individual level; the report shows actual vs. target with color-coded variance
</td> - **Drill-Down Grouping** -- group by chapter, role, management level, country, or custom dimensions
</tr> - **Active Filters** -- same powerful filter set as the timeline, applied consistently
</table> - **Export** -- one-click Excel and CSV export with all visible data, formatting preserved
### Chargeability Overview
<p align="center">
<img src="docs/screenshots/chargeability-dark.jpeg" alt="Chargeability Overview" width="100%" />
</p>
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
<p align="center">
<img src="docs/screenshots/allocations-dark.jpeg" alt="Allocations" width="100%" />
</p>
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
<p align="center">
<img src="docs/screenshots/dashboard-widgets-dark.jpeg" alt="Dashboard Widgets" width="100%" />
</p>
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
<p align="center">
<img src="docs/screenshots/admin-clients-dark.jpeg" alt="Admin - Clients" width="100%" />
</p>
- **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 ## Tech Stack
| Layer | Technology | | Layer | Technology | Purpose |
|-------|-----------| |-------|-----------|---------|
| **Frontend** | Next.js 15 (App Router), React 19, Tailwind CSS v4 | | **Frontend** | Next.js 15 (App Router), React 19 | Server components, streaming, file-based routing |
| **API** | tRPC v11 (end-to-end type safety) | | **Styling** | Tailwind CSS v4 | Utility-first CSS with custom design tokens |
| **Database** | PostgreSQL 16 via Prisma ORM | | **API** | tRPC v11 | End-to-end type-safe RPC between client and server |
| **Auth** | Auth.js v5 with Argon2 password hashing, TOTP MFA | | **Database** | PostgreSQL 16 via Prisma ORM | Relational data with JSONB for dynamic fields |
| **Realtime** | Server-Sent Events (SSE) with Redis pub/sub | | **Auth** | Auth.js v5 | Session management, Argon2 passwords, TOTP MFA |
| **Monorepo** | pnpm workspaces + Turborepo | | **Realtime** | SSE + Redis pub/sub | Live updates without WebSocket complexity |
| **Testing** | Vitest (unit), Playwright (E2E) | | **AI** | Azure OpenAI / Gemini | Staffing suggestions, skill profile generation |
| **Containerization** | Docker Compose (dev + prod) | | **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 ### Monorepo Structure
``` ```
capakraken/ capakraken/
├── apps/web/ # Next.js frontend + API routes |
├── packages/ +-- apps/
│ ├── shared/ # Types, schemas, constants shared across packages | +-- web/ Next.js 15 application (frontend + API routes)
│ ├── db/ # Prisma schema, migrations, seed scripts | +-- src/
│ ├── engine/ # Pure calculation logic (SAH, chargeability, budget) | +-- app/ App Router pages and layouts
│ ├── staffing/ # AI-assisted staffing and capacity analysis | +-- components/ React components organized by domain
│ ├── application/ # Use-case layer (business logic orchestration) | +-- hooks/ Custom React hooks
│ ├── api/ # tRPC routers and procedures | +-- lib/ Client utilities, formatters, constants
│ └── ui/ # Shared UI components (planned) | +-- server/ Server-side auth, tRPC context
└── tooling/ |
├── docker/ # Dev container entrypoint scripts +-- packages/
├── deploy/ # Production deployment scripts | +-- shared/ Types, Zod schemas, constants (zero dependencies)
├── eslint/ # Shared ESLint config | +-- db/ Prisma schema, migrations, seed scripts
└── typescript/ # Shared tsconfig bases | +-- 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 ### Prerequisites
| Requirement | Minimum Version | | Requirement | Minimum Version | Check |
|-------------|----------------| |-------------|----------------|-------|
| **Node.js** | 20.x | | **Node.js** | 20.x | `node --version` |
| **pnpm** | 9.x | | **pnpm** | 9.x | `pnpm --version` |
| **Docker** + **Docker Compose** | Docker 24+, Compose v2 | | **Docker** | 24+ | `docker --version` |
| **Docker Compose** | v2 | `docker compose version` |
### 1. Clone and configure ### 1. Clone and configure
```bash ```bash
git clone <repository-url> capakraken git clone https://gitea.hartmut-noerenberg.com/Hartmut/plANARCHY.git capakraken
cd capakraken cd capakraken
```
# Create your environment file from the template Create your environment file:
```bash
cp .env.example .env cp .env.example .env
``` ```
@@ -137,64 +287,98 @@ Edit `.env` and fill in the required values:
```bash ```bash
# Required -- generate with: openssl rand -base64 32 # Required -- generate with: openssl rand -base64 32
NEXTAUTH_SECRET=<your-secret> NEXTAUTH_SECRET=<your-generated-secret>
# Required -- your app URL (use http://localhost:3100 for local dev) # Required -- your app URL
NEXTAUTH_URL=http://localhost:3100 NEXTAUTH_URL=http://localhost:3100
# Required for pgAdmin (any password) # Required for the pgAdmin web UI
PGADMIN_PASSWORD=admin 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) ### 2. Start with Docker (recommended)
```bash ```bash
# Start everything (PostgreSQL, Redis, MailHog, app)
bash scripts/start.sh bash scripts/start.sh
``` ```
This will: This single command 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
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) ### 3. Start without Docker (host-native)
If you prefer running Node.js directly on your machine:
```bash ```bash
# Install dependencies # Install all workspace dependencies
pnpm install pnpm install
# Start PostgreSQL and Redis (still via Docker) # Start only the infrastructure via Docker
docker compose up -d postgres redis docker compose up -d postgres redis
# Generate Prisma client and run migrations # Generate the Prisma client and apply migrations
pnpm db:generate pnpm db:generate
pnpm db:migrate pnpm db:migrate
# Start the dev server # Start the Next.js dev server with hot reload
pnpm dev pnpm dev
``` ```
### 4. Create your first user ### 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 ## Available Services
| Service | URL | Description | When running with Docker Compose, the following services are available:
|---------|-----|-------------|
| **App** | http://localhost:3100 | Main application | | Service | URL | Purpose |
| **MailHog** | http://localhost:8025 | Email testing UI (catches all outgoing mail) | |---------|-----|---------|
| **pgAdmin** | http://localhost:5050 | Database administration | | **CapaKraken App** | [localhost:3100](http://localhost:3100) | Main application |
| **PostgreSQL** | localhost:5433 | Direct database access | | **MailHog** | [localhost:8025](http://localhost:8025) | Email testing UI -- catches all outgoing emails (invitations, password resets, notifications) |
| **Redis** | localhost:6380 | Cache and pub/sub | | **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 ### Application Lifecycle
```bash | Command | Description |
bash scripts/start.sh # Start all services |---------|-------------|
bash scripts/stop.sh # Stop all services | `bash scripts/start.sh` | Start all services (PostgreSQL, Redis, app) |
bash scripts/restart.sh # Stop + start | `bash scripts/stop.sh` | Stop all services gracefully |
``` | `bash scripts/restart.sh` | Full stop + start cycle |
### Development ### Development
```bash | Command | Description |
pnpm dev # Start Next.js dev server (host-native) |---------|-------------|
pnpm build # Production build | `pnpm dev` | Start Next.js dev server with hot reload (host-native) |
pnpm lint # ESLint across all packages | `pnpm build` | Production build (standalone output) |
pnpm test:unit # Run unit tests (Vitest) | `pnpm lint` | Run ESLint across all packages |
pnpm test:e2e # Run E2E tests (Playwright) | `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 ### Database
```bash | Command | Description |
pnpm db:generate # Regenerate Prisma client |---------|-------------|
pnpm db:migrate # Create and apply migrations | `pnpm db:generate` | Regenerate Prisma client after schema changes |
pnpm db:push # Push schema changes (no migration file) | `pnpm db:migrate` | Create and apply new migrations |
pnpm db:studio # Open Prisma Studio | `pnpm db:push` | Push schema changes directly (no migration file) |
pnpm db:seed # Seed demo data | `pnpm db:studio` | Open Prisma Studio (visual data browser) |
pnpm db:doctor # Health check on database state | `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 |
### Quality Gates | `pnpm db:seed:import` | Import a previously exported seed file |
```bash
pnpm test:unit # Unit tests
pnpm --filter @capakraken/web exec tsc --noEmit # Type check
pnpm lint # Linting
pnpm check:architecture # Architecture guardrails
```
--- ---
## Production Deployment ## 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 ```bash
# Set required environment variables # Configure required secrets
export APP_IMAGE=ghcr.io/your-org/capakraken-app:latest export APP_IMAGE=ghcr.io/your-org/capakraken-app:latest
export MIGRATOR_IMAGE=ghcr.io/your-org/capakraken-migrator:latest export MIGRATOR_IMAGE=ghcr.io/your-org/capakraken-migrator:latest
export POSTGRES_PASSWORD=<strong-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 bash tooling/deploy/deploy-compose.sh production
``` ```
The production stack includes: ### Production Stack Features
- Multi-stage Docker build with standalone Next.js output
- Automatic database migrations via a sidecar migrator container - **Multi-stage Docker build** -- optimized standalone Next.js output (~150 MB image)
- Redis with password authentication - **Sidecar migrator** -- runs Prisma migrations before the app starts, then exits
- Health check and readiness probe at `/api/ready` - **Redis authentication** -- password-protected with `--requirepass`
- Configurable via environment files (`.env.production`, `deploy.env`) - **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 ## 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 | | Variable | Required | Default | Description |
|----------|----------|-------------| |----------|----------|---------|-------------|
| `NEXTAUTH_URL` | Yes | Public app URL | | `NEXTAUTH_URL` | Yes | -- | Public URL of the application |
| `NEXTAUTH_SECRET` | Yes | JWT signing secret | | `NEXTAUTH_SECRET` | Yes | -- | Secret for JWT signing and session encryption |
| `DATABASE_URL` | Yes | PostgreSQL connection string | | `DATABASE_URL` | Yes | `localhost:5433` | PostgreSQL connection string |
| `REDIS_PASSWORD` | Prod | Redis authentication | | `REDIS_PASSWORD` | Prod | -- | Redis authentication password |
| `SMTP_HOST` | No | Email delivery (optional, configurable via Admin UI) | | `REDIS_URL` | No | `redis://redis:6379` | Redis connection (auto-configured in Docker) |
| `AZURE_OPENAI_API_KEY` | No | AI-assisted staffing features | | `SMTP_HOST` | No | -- | SMTP server for email delivery |
| `GEMINI_API_KEY` | No | Alternative AI provider | | `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 | Principle | Implementation |
|-----------|---------------|
The codebase follows a clean layered architecture: | **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 |
UI (apps/web) | **Pure engine logic** | Calculation packages have zero I/O dependencies -- they take data in and return results |
↓ tRPC calls | **Real-time by default** | SSE pushes changes to all clients via Redis pub/sub; no polling |
API (packages/api) | **Theme-aware UI** | CSS variable-based surface system with configurable accent colors and full dark mode |
↓ orchestrates | **Defensive data handling** | Nullable foreign keys handled explicitly; Prisma enums and JSONB cast at boundaries |
Application (packages/application) | **No speculative abstractions** | Build what's needed now; three similar lines beat a premature abstraction |
↓ 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
--- ---
## Contributing ## Contributing
1. Create a feature branch from `main` 1. Create a feature branch from `main`
2. Follow the existing code style (ESLint + Prettier enforce it) 2. Follow the existing code style -- ESLint and Prettier enforce it automatically
3. Add tests for new business logic (especially in `packages/engine`) 3. Add unit tests for new business logic, especially in `packages/engine`
4. Ensure all quality gates pass before opening a PR 4. Run quality gates before submitting:
5. Keep commits focused and well-described ```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
--- ---