CapaKraken/docs/ai-excellence-due-diligence-roadmap.md

AI Excellence Due Diligence And Roadmap

Date: 2026-03-29 Purpose: Frank assessment of the current codebase plus a pragmatic roadmap to turn CapaKraken into a reference project for disciplined AI-assisted software engineering.

Executive Summary

CapaKraken is already well beyond a prototype. The repository shows a real domain model, a non-trivial bounded-context split, a meaningful automated test baseline, and active delivery discipline.

At the same time, the codebase still carries several risks that are typical of fast-moving AI-assisted development:

1. some critical cross-cutting concerns are only partially productized
2. several files and routers have grown beyond comfortable ownership size
3. broad read access and global real-time fan-out still leak too much internal state
4. spreadsheet import parsing remains a security and reliability weak point
5. the current operational model is improving, but not yet fully standardized

The project feels strong enough to build on, but it is not yet a showcase of "how AI-built software should look" without another cleanup and hardening pass.

Current Strengths

• Clear monorepo and package split across api, application, db, engine, shared, staffing, ui, and web, with shared tooling through turbo and pnpm.
• Product scope is substantial and business-oriented rather than CRUD-only: estimating, planning, demand/assignment, chargeability, import/export, dashboards, report building, and admin surfaces.
• CI already enforces typecheck, lint, unit tests, build, and E2E with PostgreSQL and Redis in the loop.
• Application-layer use cases exist and are not just thin router wrappers.
• Documentation coverage is materially better than average for a fast-moving product.

Due Diligence Findings

Critical

1. Real-time SSE delivery is still global instead of audience-scoped. Evidence: route.ts subscribes any authenticated user to the same bus, and event-bus.ts maintains one global subscriber set and broadcasts events without per-user or per-role filtering. Risk: internal planning, vacation, budget, task, and notification metadata can be over-shared to authenticated users who should not see global changes.

2. Untrusted spreadsheet parsing still depends on xlsx@0.18.5. Evidence: import parsing remains in read-workbook.ts, browser-side parsing remains in excel.ts and skillMatrixParser.ts, and the package is still declared in apps/web/package.json and packages/application/package.json. Risk: file-import attack surface remains higher than acceptable for a flagship reference implementation.

High

1. Several high-sensitivity read paths are still too broad for least-privilege. Evidence: multiple planning, resource, project, dashboard, allocation, and timeline reads still use protectedProcedure rather than narrower role-specific gates in dashboard.ts, timeline.ts, allocation.ts, resource.ts, and project.ts. Risk: authorization intent remains hard to reason about and easy to regress.

2. Router and UI module size is now an operational risk. Evidence: assistant-tools.ts, resource.ts, allocation.ts, timeline.ts, vacation.ts, and large frontend files such as SystemSettingsClient.tsx and TimelineProjectPanel.tsx are each well past the size where safe ownership stays easy. Risk: AI-generated changes become harder to review, humans lose local reasoning context, and regressions become more likely.

3. Secret handling is still application-database centric. Evidence: system settings mutate and persist API keys and SMTP credentials in settings.ts. Risk: operational secrets remain too coupled to the main app data plane for a gold-standard project.

Medium

1. Rate limiting is process-local and not deployment-grade. Evidence: rate-limit.ts uses an in-memory Map and explicitly notes that multi-instance deployments need Redis-backed replacement. Risk: protections weaken as soon as the app scales horizontally.

2. Performance hotspots are well understood but not yet structurally solved. Evidence: the current performance review identifies repeated in-memory filtering, broad invalidation, and heavyweight timeline/report derivations in performance-optimization-review-2026-03-18.md. Risk: user experience and infrastructure cost will degrade as data volume grows.

3. Production delivery is still in transition. Evidence: the current repo now has a target CI/CD path, but the old manual production path still coexists with the new image-based deploy model in cicd-target-architecture.md. Risk: the operational source of truth is not yet singular.

Overall Rating

Product Engineering Quality

8/10

This is materially better than a typical startup CRUD app and already has the bones of a serious internal platform or vertical SaaS.

Security Posture

6/10

There are good foundations, but the remaining SSE, spreadsheet, and least-privilege gaps are not acceptable for a "parade example" yet.

Maintainability

6.5/10

The architecture is promising, but file size, router density, and compatibility residue will eventually slow everyone down unless addressed deliberately.

Operational Maturity

6.5/10

Good CI and improving deploy discipline are in place, but production standardization still needs one more step.

AI-Excellence Readiness

6/10

The project already proves that AI can help build serious software fast. It does not yet prove that AI-assisted development can stay consistently clean, minimal, and audit-friendly at scale.

What A Showcase AI Project Should Demonstrate

To be a true showcase for AI-assisted development, this repository should visibly demonstrate:

• small, composable files with clear ownership boundaries
• explicit security and permission models at every boundary
• deterministic build and deploy flow
• measurable quality gates beyond "tests pass"
• strong documentation that explains not only what exists, but why the structure is this way
• low-friction reviewability, so humans can still govern AI speed

Roadmap

Phase 1: Close the Dangerous Gaps

Target window: 1 to 2 weeks

Goals:

• Replace global SSE fan-out with audience-aware channels.
• Remove xlsx from untrusted import paths or isolate it behind a hardened parser boundary.
• Create a route access matrix and reclassify broad protectedProcedure read endpoints.
• Move production secrets out of regular application settings, or add an interim encrypted-secrets layer with clear migration path.

Definition of done:

• standard users cannot subscribe to unrelated real-time planning events
• file import paths have documented limits and safer parsing
• every sensitive router is explicitly classified by audience
• secret storage policy is documented and enforced

Phase 2: Cut Down Complexity

Target window: 2 to 4 weeks

Goals:

• Split oversized routers into bounded router modules by feature slice.
• Split oversized React components into container, state, and presentational layers.
• Introduce file-size and complexity guardrails for new code.
• Create "AI review rules" for generated patches: max file growth, required tests, required docs for cross-cutting changes.

Priority candidates:

• packages/api/src/router/assistant-tools.ts
• packages/api/src/router/resource.ts
• packages/api/src/router/allocation.ts
• packages/api/src/router/timeline.ts
• apps/web/src/components/admin/SystemSettingsClient.tsx
• apps/web/src/components/timeline/*

Definition of done:

• no new source file over 500 lines without an explicit exception
• top 10 largest business-critical source files are materially reduced
• patch reviews become narrower and easier to reason about

Phase 3: Make Quality Measurable

Target window: 2 to 3 weeks

Goals:

• Add architecture fitness checks, not just lint/tests.
• Add API authorization tests for all sensitive routers.
• Add bundle-size and route-size monitoring for the web app.
• Add mutation-path audit coverage checks where business-critical state changes occur.
• Add a dependency and unsafe-library policy.

Suggested checks:

• role/permission regression tests
• SSE audience contract tests
• import abuse tests with oversized files
• max file size / max router size lint or CI checks
• coverage thresholds for critical packages

Definition of done:

• the repo can fail CI for architectural regressions, not only syntax or unit failures
• critical security assumptions are test-backed

Phase 4: Standardize Operations

Target window: 1 to 2 weeks

Goals:

• complete the move to image-based deploys as the canonical path
• document staging and production bootstrap as code, not tribal knowledge
• replace in-memory rate limits with Redis-backed limits where appropriate
• define rollback drills and incident response playbooks

Definition of done:

• one production deployment path
• one rollback path
• one source of truth for runtime configuration

Phase 5: Turn It Into A Reference Project

Target window: ongoing

Goals:

• add a concise engineering doctrine for AI-assisted development in this repo
• publish coding heuristics for humans and AI: file size limits, change budgets, ownership boundaries, review expectations
• maintain a "why this is structured this way" architecture guide
• log selected before/after refactors to demonstrate how AI was used responsibly

Artifacts to add:

• docs/engineering-doctrine.md
• docs/architecture-decision-records/
• docs/ai-collaboration-standards.md
• a small set of "reference slices" that show exemplary patterns end to end

Suggested Order Of Execution

1. SSE scoping
2. spreadsheet import hardening
3. access-matrix and authorization tightening
4. secrets policy
5. router/component decomposition
6. architecture fitness checks in CI
7. full operational standardization

Success Criteria For The Next 60 Days

• no critical or high-severity known security gap remains open without an owner and due date
• no core router continues to grow unchecked
• at least one major domain slice is refactored into a clear "reference implementation" pattern
• production deployment uses the same artifact that passed CI
• the repo gains explicit AI-development rules that improve reviewability instead of just increasing output

Bottom Line

CapaKraken is already good enough to justify further investment. It is not a cleanup disaster.

The opportunity is not to rebuild it. The opportunity is to harden the weak edges, reduce oversized ownership surfaces, and make the engineering standards visible enough that the repository becomes evidence that AI can accelerate serious software without normalizing architectural debt.