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

docs: add project README with screenshots and setup guide

Browse Source 
- Hero dashboard screenshot, badge bar, and feature overview
- 6-screenshot gallery (timeline, chargeability, allocations, widgets, admin)
- Tech stack table and monorepo structure diagram
- Getting started guide (Docker + host-native)
- Service reference, scripts reference, production deployment guide
- Environment variables reference and architecture overview

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Hartmut Nörenberg
2026-04-10 14:07:08 +02:00
parent 78d50b78d3
commit 600a86ca71
9 changed files with 329 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+329
View File
@@ -0,0 +1,329 @@
<p align="center">
<img src="docs/screenshots/dashboard-dark.jpeg" alt="CapaKraken Dashboard" width="100%" />
</p>
<h1 align="center">CapaKraken</h1>
<p align="center">
<strong>Resource &amp; Capacity Planning for 3D Production Studios</strong>
</p>
<p align="center">
<em>Plan teams. Track chargeability. Forecast budgets. Staff smarter.</em>
</p>
<p align="center">
<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="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-16-336791?logo=postgresql&logoColor=white" />
<img alt="tRPC" 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="Tailwind CSS" src="https://img.shields.io/badge/Tailwind-v4-38bdf8?logo=tailwindcss&logoColor=white" />
<img alt="License" src="https://img.shields.io/badge/License-Proprietary-red" />
</p>
---
## What is CapaKraken?
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.
### 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
---
## Screenshots
<table>
<tr>
<td width="50%">
<img src="docs/screenshots/timeline-resource-dark.jpeg" alt="Timeline - Resource View" /><br />
<em>Timeline with resource allocations, vacation overlays, and weekend highlighting</em>
</td>
<td width="50%">
<img src="docs/screenshots/chargeability-detail-dark.jpeg" alt="Chargeability Report" /><br />
<em>Chargeability forecast with monthly breakdown and holiday deduction rules</em>
</td>
</tr>
<tr>
<td width="50%">
<img src="docs/screenshots/allocations-dark.jpeg" alt="Allocations" /><br />
<em>Allocation management with status badges, project grouping, and inline editing</em>
</td>
<td width="50%">
<img src="docs/screenshots/dashboard-widgets-dark.jpeg" alt="Dashboard Widgets" /><br />
<em>Customizable dashboard with widget catalog and drag-and-drop layout</em>
</td>
</tr>
<tr>
<td width="50%">
<img src="docs/screenshots/admin-clients-dark.jpeg" alt="Admin - Clients" /><br />
<em>Client hierarchy management with drag-and-drop reordering</em>
</td>
<td width="50%">
<img src="docs/screenshots/chargeability-dark.jpeg" alt="Chargeability Overview" /><br />
<em>Chargeability overview with per-resource utilization heatmap</em>
</td>
</tr>
</table>
---
## 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) |
### 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
```
---
## Getting Started
### Prerequisites
| Requirement | Minimum Version |
|-------------|----------------|
| **Node.js** | 20.x |
| **pnpm** | 9.x |
| **Docker** + **Docker Compose** | Docker 24+, Compose v2 |
### 1. Clone and configure
```bash
git clone <repository-url> capakraken
cd capakraken
# Create your environment file from the template
cp .env.example .env
```
Edit `.env` and fill in the required values:
```bash
# Required -- generate with: openssl rand -base64 32
NEXTAUTH_SECRET=<your-secret>
# Required -- your app URL (use http://localhost:3100 for local dev)
NEXTAUTH_URL=http://localhost:3100
# Required for pgAdmin (any password)
PGADMIN_PASSWORD=admin
```
The database connection, Redis, and SMTP are pre-configured for Docker Compose and work out of the box.
### 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
Once ready, open **http://localhost:3100** in your browser.
### 3. Start without Docker (host-native)
```bash
# Install dependencies
pnpm install
# Start PostgreSQL and Redis (still via Docker)
docker compose up -d postgres redis
# Generate Prisma client and run migrations
pnpm db:generate
pnpm db:migrate
# Start the dev server
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.
---
## 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 |
---
## Scripts Reference
### Application Lifecycle
```bash
bash scripts/start.sh # Start all services
bash scripts/stop.sh # Stop all services
bash scripts/restart.sh # Stop + start
```
### 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)
```
### 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
```
---
## Production Deployment
CapaKraken ships with a Docker Compose production stack (`docker-compose.prod.yml`) and a deployment script:
```bash
# Set required environment variables
export APP_IMAGE=ghcr.io/your-org/capakraken-app:latest
export MIGRATOR_IMAGE=ghcr.io/your-org/capakraken-migrator:latest
export POSTGRES_PASSWORD=<strong-password>
# Deploy
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`)
---
## Environment Variables
See [`.env.example`](.env.example) for the full reference with descriptions. 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 |
---
## Project Structure Highlights
### 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
---
## 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
---
## License
Proprietary. All rights reserved.
---
<p align="center">
<sub>Built with TypeScript, Next.js, and a lot of coffee.</sub>
</p>