chore(repo): checkpoint current capakraken implementation state
This commit is contained in:
@@ -1,11 +1,11 @@
|
||||
# Planarchy V2 Architecture Proposal
|
||||
# CapaKraken V2 Architecture Proposal
|
||||
|
||||
**Date:** 2026-03-11
|
||||
**Scope:** Codebase review, v2 direction, architecture rethink, parallel agent strategy
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Planarchy already has a good base:
|
||||
CapaKraken already has a good base:
|
||||
- monorepo boundaries are mostly clean
|
||||
- `engine` and `staffing` contain useful pure domain logic
|
||||
- Next.js + tRPC + Prisma keeps product iteration fast
|
||||
@@ -44,31 +44,31 @@ This gives you a v2 that is safer, easier to change, and still realistic for a s
|
||||
## 1. Critical correctness and security issues exist today
|
||||
|
||||
### Auth hashing is inconsistent
|
||||
- Login verifies Argon2 hashes in [`apps/web/src/server/auth.ts#L20`](/home/hartmut/Documents/Copilot/planarchy/apps/web/src/server/auth.ts#L20).
|
||||
- Admin-created users are still stored with SHA-256 in [`packages/api/src/router/user.ts#L41`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/user.ts#L41).
|
||||
- Login verifies Argon2 hashes in [`apps/web/src/server/auth.ts#L20`](/home/hartmut/Documents/Copilot/capakraken/apps/web/src/server/auth.ts#L20).
|
||||
- Admin-created users are still stored with SHA-256 in [`packages/api/src/router/user.ts#L41`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/user.ts#L41).
|
||||
- Impact: users created from the admin flow are likely unable to log in.
|
||||
|
||||
### Notification creation is open to any authenticated user
|
||||
- `notification.create` is only `protectedProcedure` in [`packages/api/src/router/notification.ts#L66`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/notification.ts#L66).
|
||||
- `notification.create` is only `protectedProcedure` in [`packages/api/src/router/notification.ts#L66`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/notification.ts#L66).
|
||||
- Impact: any logged-in user can create notifications for arbitrary users.
|
||||
|
||||
### AI connection testing is Azure-shaped even when provider is OpenAI
|
||||
- `testAiConnection` always constructs an Azure deployment URL in [`packages/api/src/router/settings.ts#L122`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/settings.ts#L122).
|
||||
- `testAiConnection` always constructs an Azure deployment URL in [`packages/api/src/router/settings.ts#L122`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/settings.ts#L122).
|
||||
- Impact: provider abstraction is not actually reliable.
|
||||
|
||||
### Repo health checks are currently failing
|
||||
- `pnpm test:unit` fails because `@capakraken/shared` has a Vitest script but no tests in [`packages/shared/package.json`](/home/hartmut/Documents/Copilot/planarchy/packages/shared/package.json).
|
||||
- `pnpm typecheck` fails because `crypto.randomUUID()` is used without a visible import/global typing in [`packages/shared/src/schemas/project.schema.ts#L5`](/home/hartmut/Documents/Copilot/planarchy/packages/shared/src/schemas/project.schema.ts#L5).
|
||||
- `pnpm test:unit` fails because `@capakraken/shared` has a Vitest script but no tests in [`packages/shared/package.json`](/home/hartmut/Documents/Copilot/capakraken/packages/shared/package.json).
|
||||
- `pnpm typecheck` fails because `crypto.randomUUID()` is used without a visible import/global typing in [`packages/shared/src/schemas/project.schema.ts#L5`](/home/hartmut/Documents/Copilot/capakraken/packages/shared/src/schemas/project.schema.ts#L5).
|
||||
|
||||
These are not “v2 someday” items. They should be fixed before deeper refactoring.
|
||||
|
||||
## 2. Large surfaces are carrying too much responsibility
|
||||
|
||||
The biggest modules are already a warning sign:
|
||||
- [`apps/web/src/components/timeline/TimelineView.tsx`](/home/hartmut/Documents/Copilot/planarchy/apps/web/src/components/timeline/TimelineView.tsx) is 1720 lines.
|
||||
- [`apps/web/src/components/projects/ProjectWizard.tsx`](/home/hartmut/Documents/Copilot/planarchy/apps/web/src/components/projects/ProjectWizard.tsx) is 1171 lines.
|
||||
- [`packages/api/src/router/resource.ts`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/resource.ts) is 908 lines.
|
||||
- [`packages/api/src/router/timeline.ts`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/timeline.ts) is 631 lines.
|
||||
- [`apps/web/src/components/timeline/TimelineView.tsx`](/home/hartmut/Documents/Copilot/capakraken/apps/web/src/components/timeline/TimelineView.tsx) is 1720 lines.
|
||||
- [`apps/web/src/components/projects/ProjectWizard.tsx`](/home/hartmut/Documents/Copilot/capakraken/apps/web/src/components/projects/ProjectWizard.tsx) is 1171 lines.
|
||||
- [`packages/api/src/router/resource.ts`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/resource.ts) is 908 lines.
|
||||
- [`packages/api/src/router/timeline.ts`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/timeline.ts) is 631 lines.
|
||||
|
||||
That usually means:
|
||||
- transport, orchestration, validation, business rules, and data access are mixed
|
||||
@@ -78,10 +78,10 @@ That usually means:
|
||||
## 3. The core planning model is overloaded
|
||||
|
||||
The Prisma schema uses JSONB heavily in core workflows:
|
||||
- blueprints and role presets in [`packages/db/prisma/schema.prisma#L147`](/home/hartmut/Documents/Copilot/planarchy/packages/db/prisma/schema.prisma#L147)
|
||||
- resource availability, skills, and dynamic fields in [`packages/db/prisma/schema.prisma#L208`](/home/hartmut/Documents/Copilot/planarchy/packages/db/prisma/schema.prisma#L208)
|
||||
- project staffing requirements and dynamic fields in [`packages/db/prisma/schema.prisma#L267`](/home/hartmut/Documents/Copilot/planarchy/packages/db/prisma/schema.prisma#L267)
|
||||
- allocation metadata in [`packages/db/prisma/schema.prisma#L301`](/home/hartmut/Documents/Copilot/planarchy/packages/db/prisma/schema.prisma#L301)
|
||||
- blueprints and role presets in [`packages/db/prisma/schema.prisma#L147`](/home/hartmut/Documents/Copilot/capakraken/packages/db/prisma/schema.prisma#L147)
|
||||
- resource availability, skills, and dynamic fields in [`packages/db/prisma/schema.prisma#L208`](/home/hartmut/Documents/Copilot/capakraken/packages/db/prisma/schema.prisma#L208)
|
||||
- project staffing requirements and dynamic fields in [`packages/db/prisma/schema.prisma#L267`](/home/hartmut/Documents/Copilot/capakraken/packages/db/prisma/schema.prisma#L267)
|
||||
- allocation metadata in [`packages/db/prisma/schema.prisma#L301`](/home/hartmut/Documents/Copilot/capakraken/packages/db/prisma/schema.prisma#L301)
|
||||
|
||||
The bigger modeling problem is that **`Allocation` currently represents both demand and assignment**:
|
||||
- placeholder demand is modeled with `resourceId = null`
|
||||
@@ -95,7 +95,7 @@ This is the wrong aggregate for v2.
|
||||
`staffing.getSuggestions` currently:
|
||||
- loads all active resources with overlapping allocations
|
||||
- computes utilization in the router
|
||||
- uses only Monday availability as the denominator in [`packages/api/src/router/staffing.ts#L45`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/staffing.ts#L45)
|
||||
- uses only Monday availability as the denominator in [`packages/api/src/router/staffing.ts#L45`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/staffing.ts#L45)
|
||||
|
||||
That means the suggestion layer is:
|
||||
- hard to scale
|
||||
@@ -105,8 +105,8 @@ That means the suggestion layer is:
|
||||
## 5. Routers are doing application-service work
|
||||
|
||||
Representative examples:
|
||||
- timeline queries and update workflows live directly in [`packages/api/src/router/timeline.ts#L12`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/timeline.ts#L12)
|
||||
- allocation creation, placeholder fill, validation, vacation handling, cost calc, audit log, and event emission all live in [`packages/api/src/router/allocation.ts#L8`](/home/hartmut/Documents/Copilot/planarchy/packages/api/src/router/allocation.ts#L8)
|
||||
- timeline queries and update workflows live directly in [`packages/api/src/router/timeline.ts#L12`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/timeline.ts#L12)
|
||||
- allocation creation, placeholder fill, validation, vacation handling, cost calc, audit log, and event emission all live in [`packages/api/src/router/allocation.ts#L8`](/home/hartmut/Documents/Copilot/capakraken/packages/api/src/router/allocation.ts#L8)
|
||||
|
||||
The pure `engine` package exists, but the application layer that should orchestrate it does not.
|
||||
|
||||
@@ -530,4 +530,4 @@ It should be:
|
||||
- read models for planning screens
|
||||
- normalized planning entities with JSONB reserved for extension points
|
||||
|
||||
That will make Planarchy better at the thing it claims to be: a planning system, not just a CRUD app with a timeline.
|
||||
That will make CapaKraken better at the thing it claims to be: a planning system, not just a CRUD app with a timeline.
|
||||
|
||||
Reference in New Issue
Block a user