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

feat: unified Skills Hub — merge analytics + marketplace into one page

Browse Source 
Combines SkillsAnalytics (496 LOC) and SkillMarketplace (346 LOC) into
a single tabbed Skills Hub (770 LOC total, -9% code).

New structure:
- skills/shared.tsx: ProficiencyBadge, GapIndicator, constants (extracted)
- skills/OverviewTab.tsx: KPI cards, top 10 table, distribution chart, export
- skills/SearchTab.tsx: skill search + proficiency + availability filter
- skills/GapsTab.tsx: supply vs demand table with gap indicators
- skills/PeopleFinderTab.tsx: multi-rule AND/OR builder, chapter filter, export
- SkillsHub.tsx: tabbed container with URL-persisted tab state (?tab=)

Routing:
- /analytics/skills renders SkillsHub (was SkillsAnalytics)
- /analytics/skill-marketplace redirects to /analytics/skills?tab=search
- Sidebar: "Skill Marketplace" removed, renamed to "Skills Hub"

No API changes — reuses existing queries with conditional fetching per tab.
Full dark theme support on all components.

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
Hartmut Nörenberg
2026-03-22 21:33:21 +01:00
parent 1f4c230b8b
commit c7b76e086d
10 changed files with 901 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plan.md
+125 -265
View File
@@ -1,265 +1,125 @@
# Planarchy — Product Owner Strategic Plan
> Consolidated analysis from 4 expert agents: Roadmap, API Surface, Frontend UX, and Test Infrastructure.
> Date: 2026-03-19
---
## Executive Summary
Planarchy has reached **Phase 9** with a mature core: timeline planning, allocation management, estimating, vacation pro, skill matrix, RBAC, and chargeability reporting. The product covers 34 routes, 47 DB models, ~200 tRPC procedures, and 109+ domain components.
**However, the product has critical gaps preventing production readiness and growth:**
| Dimension | Score | Verdict |
|-----------|-------|---------|
| Feature completeness | 85% | Strong core, thin edges (staffing, reporting) |
| Code quality | 90% | Zero TODOs, clean architecture, typed end-to-end |
| Test coverage | 55% | Engine excellent, API routers ~5%, no integration tests |
| CI/CD & DevOps | 10% | No pipeline, no prod Docker, no monitoring |
| UX polish | 75% | Deep timeline/estimates, but gaps in staffing workflow |
| Growth readiness | 40% | No scenario planning, no integrations, no mobile |
---
## Part 1: Bottlenecks
### 1.1 Production Readiness Blockers (Critical)
| # | Bottleneck | Impact | Severity |
|---|-----------|--------|----------|
| B1 | **No CI/CD pipeline** — tests, lint, tsc not automated on PR | Regressions ship undetected | CRITICAL |
| B2 | **No production Docker image** — only dev Dockerfile exists | Cannot deploy containerized | CRITICAL |
| B3 | **No monitoring/logging** — no Sentry, no Pino, no APM | Blind in production, cannot debug | CRITICAL |
| B4 | **No health check endpoints** — `/health`, `/ready` missing | Cannot detect/recover from failures | HIGH |
| B5 | **API router test coverage ~5%** — 28 routers, almost no unit tests | Mutations untested at API boundary | HIGH |
### 1.2 UX Bottlenecks
| # | Bottleneck | Impact | Severity |
|---|-----------|--------|----------|
| B6 | **Staffing -> Allocation gap** — match results don't link to allocation creation | Users must manually recreate allocations after finding matches | HIGH |
| B7 | **Reporting is thin** — only 2 report types (chargeability, PDF allocations) | Finance/PMs can't self-serve custom reports | MEDIUM |
| B8 | **No bulk operations in list views** — no multi-select outside timeline | Slow to manage 10+ resources/projects at once | MEDIUM |
| B9 | **Dashboard metrics computed live** — no caching/pre-computation | Slow dashboard load with growing data | MEDIUM |
| B10 | **Timeline 3.3K LOC ecosystem** — ResourcePanel 1035, ProjectPanel 1315 LOC | Hard to maintain, risky to modify | LOW |
### 1.3 Architecture Bottlenecks
| # | Bottleneck | Impact | Severity |
|---|-----------|--------|----------|
| B11 | **Prisma client cache invalidation** — dev server restart required after schema changes | Developer friction, CI complexity | MEDIUM |
| B12 | **No webhook/event outbound** — SSE event bus exists but no external subscriptions | Cannot notify external systems (Slack, Jira) | MEDIUM |
| B13 | **No soft-delete strategy** — mixed approach (isActive, status, hard delete) | Data loss risk, no audit trail on deletions | LOW |
| B14 | **Rate card lookup manual in estimates** — no auto-lookup by resource chapter/level | Estimate creation slower than needed | LOW |
---
## Part 2: Growth Potential
### 2.1 High-Value Feature Opportunities
#### Tier 1 — Quick Wins (1-3 days each)
| # | Feature | Value | Effort |
|---|---------|-------|--------|
| G1 | **Staffing "Assign" button** — pre-populate allocation modal from match result | Closes biggest UX gap, saves 5+ clicks per staffing decision | 1-2 days |
| G2 | **Dashboard caching** — pre-compute metrics, invalidate on SSE events | 3-5x dashboard load speed improvement | 1-2 days |
| G3 | **Bulk list operations** — multi-select + context menu on resources/projects | Enables batch edit, export, status change | 2-3 days |
| G4 | **Health check endpoints** — `/api/health` (liveness), `/api/ready` (DB + Redis) | Production deployment prerequisite | 0.5 day |
#### Tier 2 — Strategic Features (1-2 weeks each)
| # | Feature | Value | Effort |
|---|---------|-------|--------|
| G5 | **Scenario/What-If Planning** — alternate staffing mixes, cost simulations | Differentiation for PMs and finance; leverages existing engine | 1-2 weeks |
| G6 | **Skill Marketplace** — searchable skill inventory, gap heat map, hiring priorities | High leverage from existing skill matrix; enables org-wide planning | 1 week |
| G7 | **Custom Report Builder** — drag columns, pivot, grouping, scheduled exports | Unlocks self-service analytics for finance and executives | 1-2 weeks |
| G8 | **Collaboration Layer** — inline comments on estimates, @mention, approval feedback | Enables cross-functional workflows (finance, PM, staffing) | 1-2 weeks |
#### Tier 3 — Market Differentiators (2-4 weeks each)
| # | Feature | Value | Effort |
|---|---------|-------|--------|
| G9 | **AI-Powered Insights** — auto-suggest staffing, anomaly detection, narrative reports | Leverages existing Azure OpenAI integration; executive decision support | 2-3 weeks |
| G10 | **External Integrations** — Jira/Linear sync, Slack notifications, Google Calendar | Stickiness; connects Planarchy into existing workflows | 2-4 weeks |
| G11 | **Mobile Companion** — PWA with quick-view (status, gaps, approvals, push notifications) | Engagement for field PMs and remote staff | 3-4 weeks |
| G12 | **Dispo V2 Clean-Slate Import** — design doc + tickets exist, ready for implementation | Unblocks migration from legacy system; critical for customer onboarding | 1-2 weeks |
### 2.2 Missing Dashboard Widgets
| Widget | Purpose | Effort |
|--------|---------|--------|
| Budget spend forecast | Forward-looking actuals vs budget trend line | 2 days |
| Team utilization heatmap | Resource x week grid with color intensity | 2 days |
| Skill gap analysis | Required vs available skills across open demands | 3 days |
| Project health scorecard | On-time, on-budget, quality composite score | 2 days |
| Hiring pipeline | Forecast unfilled demand 3-6 months out | 3 days |
---
## Part 3: Automation Potential
### 3.1 Development Workflow Automation
| # | Automation | Current State | Target | Effort |
|---|-----------|--------------|--------|--------|
| A1 | **CI/CD Pipeline** | None | GitHub Actions: test + lint + tsc on PR, build + deploy on merge | 1-2 days |
| A2 | **Dependency scanning** | None | Dependabot + npm audit in CI | 0.5 day |
| A3 | **E2E test suite expansion** | 4 specs (auth, timeline, projects, resources) | 20+ specs covering key user flows | 1 week |
| A4 | **API integration tests** | ~5% router coverage | 80% coverage with mock DB layer | 1-2 weeks |
| A5 | **Coverage gates** | Engine 95%, staffing 90%, others none | All packages minimum 80% | 2 days config |
### 3.2 Business Process Automation
| # | Automation | Current Manual Process | Automated Process | Effort |
|---|-----------|----------------------|-------------------|--------|
| A6 | **Auto-staffing suggestions** | PM manually searches for resources per demand | System proposes top-3 matches when demand is created | 3 days |
| A7 | **Vacation conflict alerts** | Manager manually checks team calendar before approving | Auto-detect overlap > threshold, flag in approval flow | 2 days |
| A8 | **Budget overrun notifications** | Finance checks dashboards manually | SSE-triggered notification when project hits 80%/100% budget | 1 day |
| A9 | **Estimate approval reminders** | Verbal follow-up | Scheduled notification after N days in SUBMITTED status | 1 day |
| A10 | **Chargeability alerts** | Monthly manual review | Weekly auto-email when resource chargeability drops below target | 2 days |
| A11 | **Rate card auto-apply** | Manual rate lookup when creating estimate demand lines | Auto-fill LCR/UCR from rate card by resource chapter + level + client | 2 days |
| A12 | **Public holiday auto-import** | Admin manually batch-creates per year | Auto-generate on year rollover based on country/state config | 1 day |
### 3.3 Monitoring & Observability Automation
| # | Automation | Target | Effort |
|---|-----------|--------|--------|
| A13 | **Structured logging** (Pino) | All API requests logged with correlation ID | 2 days |
| A14 | **Error tracking** (Sentry) | Unhandled exceptions captured with context | 1 day |
| A15 | **Performance monitoring** | Slow query detection, API response time tracking | 2 days |
| A16 | **Uptime monitoring** | External health check probe, alerting | 0.5 day |
---
## Part 4: Prioritized Roadmap
### Sprint 0: Production Foundation (Week 1)
**Goal:** Unblock production deployment.
- [ ] **A1** — GitHub Actions CI pipeline (test + lint + tsc + build)
- [ ] **G4** — Health check endpoints (`/api/health`, `/api/ready`)
- [ ] **A14** — Sentry error tracking integration
- [ ] **A13** — Pino structured logging in API layer
- [ ] Production Dockerfile (multi-stage, distroless base)
- [ ] docker-compose.prod.yml with env-based config
- [ ] Database backup strategy (pg_dump cron + S3)
**Acceptance:** `main` branch has green CI, production image builds, errors are captured.
### Sprint 1: Quick Wins (Week 2)
**Goal:** Close the biggest UX gaps and improve daily workflows.
- [ ] **G1** — Staffing "Assign" button (match -> allocation in 1 click)
- [ ] **G2** — Dashboard metric caching (Redis-backed, SSE-invalidated)
- [ ] **G3** — Bulk operations on resource/project lists
- [ ] **A8** — Budget overrun notifications (80% + 100% thresholds)
- [ ] **A9** — Estimate approval reminders (auto-notify after 3 days)
**Acceptance:** Staffing-to-allocation is 1 click, dashboard loads <500ms, bulk select works.
### Sprint 2: Test Coverage & Stability (Week 3)
**Goal:** Harden the codebase for confident iteration.
- [ ] **A4** — API router integration tests (target 15 most-used routers)
- [ ] **A5** — Coverage gates: api + application packages at 80%
- [ ] **A3** — E2E expansion: 10 new specs (estimate lifecycle, vacation flow, bulk ops, filters)
- [ ] **A2** — Dependabot + npm audit in CI
**Acceptance:** `pnpm test:unit` covers all routers, E2E suite runs in CI, zero high-severity vulnerabilities.
### Sprint 3: Automation & Intelligence (Week 4-5)
**Goal:** Automate repetitive decisions, surface insights proactively.
- [ ] **A6** — Auto-staffing suggestions on demand creation
- [ ] **A7** — Vacation conflict detection in approval flow
- [ ] **A10** — Weekly chargeability alerts
- [ ] **A11** — Rate card auto-apply in estimate demand lines
- [ ] **A12** — Public holiday auto-import on year rollover
- [ ] **G6** — Skill marketplace MVP (searchable inventory + gap heat map)
**Acceptance:** Demands auto-suggest resources, vacation conflicts auto-flagged, rate cards auto-filled.
### Sprint 4: Strategic Features (Week 6-8)
**Goal:** Build differentiation features that create competitive moat.
- [ ] **G5** — Scenario/what-if planning (staffing mix simulator)
- [ ] **G7** — Custom report builder MVP (column picker, filters, export)
- [ ] **G8** — Collaboration layer (comments on estimates, @mention)
- [ ] **G12** — Dispo V2 clean-slate import (leverage existing design docs + tickets)
- [ ] Dashboard new widgets: budget forecast, skill gap, project health scorecard
**Acceptance:** PMs can simulate staffing scenarios, finance can build custom reports, Dispo import onboards first customer.
### Sprint 5: Market Expansion (Week 9-12)
**Goal:** Expand the platform beyond core planning.
- [ ] **G9** — AI insights: auto-staffing, anomaly detection, narrative summaries
- [ ] **G10** — Jira/Linear integration + Slack notifications
- [ ] **G11** — Mobile PWA companion
- [ ] **A15** — Performance monitoring + load testing baseline
- [ ] Advanced: multi-tenant architecture planning
**Acceptance:** AI suggestions active, Jira sync live, mobile app installable.
---
## Part 5: Risk Register
| # | Risk | Probability | Impact | Mitigation |
|---|------|-------------|--------|------------|
| R1 | Production deployment without CI catches regressions | HIGH | CRITICAL | Sprint 0 is mandatory before any feature work |
| R2 | Timeline 3.3K LOC becomes unmaintainable | MEDIUM | HIGH | Decompose into sub-hook modules when next touching timeline |
| R3 | Dashboard performance degrades with data growth | MEDIUM | MEDIUM | G2 (caching) in Sprint 1; monitor query times |
| R4 | Prisma schema changes break dev workflow | HIGH | LOW | Automate restart in dev scripts (already documented) |
| R5 | Skill matrix AI costs grow with usage | LOW | MEDIUM | Add token budget tracking in SystemSettings |
| R6 | No data backup strategy | MEDIUM | CRITICAL | Add pg_dump cron + S3 upload in Sprint 0 |
| R7 | Single-point-of-failure (1 dev, 1 server) | HIGH | CRITICAL | Document architecture, automate deployment, enable team onboarding |
---
## Part 6: Key Metrics to Track
### Product Metrics
- **Time-to-staff**: Minutes from demand creation to resource assignment
- **Estimate turnaround**: Days from estimate creation to approval
- **Vacation approval latency**: Hours from request to decision
- **Dashboard load time**: P95 response time for dashboard page
- **Chargeability accuracy**: Forecast vs actual deviation %
### Engineering Metrics
- **Test coverage**: % by package (target: all >=80%)
- **CI green rate**: % of PRs passing all gates
- **Build time**: Minutes for full `next build`
- **Error rate**: Sentry exceptions per hour
- **API latency**: P95 tRPC procedure response time
---
## Appendix: Current State Snapshot
| Dimension | Count |
|-----------|-------|
| Database models | 47 |
| tRPC routers | 28 |
| tRPC procedures | ~200 (120Q + 80M) |
| Frontend routes | 34 |
| Domain components | 109+ |
| Shared UI components | 20+ |
| Unit test files | 62 |
| E2E test specs | 4 |
| Engine test coverage | 95% (gated) |
| Staffing test coverage | 90% (gated) |
| API router test coverage | ~5% (not gated) |
| CI/CD pipeline | None |
| Production Docker | None |
| Monitoring/APM | None |
| Completed phases | 9 |
| Known pain points | 24 (documented in LEARNINGS.md) |
# Unified Skills Hub — Plan
## Anforderungsanalyse
**Was:** Die zwei getrennten Skill-Seiten (`/analytics/skills` = SkillsAnalytics, `/analytics/skill-marketplace` = SkillMarketplace) zu **einer einzigen, nutzerfreundlichen Skills-Hub-Seite** zusammenfuehren.
**Problem heute:**
- **SkillsAnalytics** (496 LOC): Skill-Tabelle mit Filtern, People Finder (AND/OR Suche), XLSX Export, Skill Distribution Chart, Skill Gap Alerts
- **SkillMarketplace** (346 LOC): Skill-Suche mit Verfuegbarkeitsfilter, Skill Gap Heat Map (Supply vs Demand), Skill Distribution Chart (dupliziert!)
- **Ueberlappung:** Beide haben `ProficiencyBadge`, `PROFICIENCY_CLASSES`, `SkillDistributionChart`, aehnliche Tabellen
- **Verwirrung:** User muss zwei Seiten besuchen fuer zusammenhaengende Informationen
- **Inkonsistenz:** Analytics hat kein Dark-Theme auf manchen Elementen, Marketplace hat es
**Ziel:** Eine Seite `/analytics/skills` mit Tab-basiertem Layout:
```
+-------------------------------------------------------------+
| Skills Hub [Export] |
| 125 resources . 47 distinct skills |
+----------+----------+----------+-------------+--------------+
| Overview | Search | Gaps | People | Distribution |
+----------+----------+----------+-------------+--------------+
| |
| [Tab content area] |
| |
+--------------------------------------------------------------+
```
### Betroffene Pakete & Dateien
| Paket | Dateien | Art der Aenderung |
|-------|---------|------------------|
| `apps/web` | `src/components/analytics/SkillsHub.tsx` | **create** — neue unified component |
| `apps/web` | `src/components/analytics/skills/OverviewTab.tsx` | **create** — KPI cards + distribution chart |
| `apps/web` | `src/components/analytics/skills/SearchTab.tsx` | **create** — skill search + availability (from Marketplace) |
| `apps/web` | `src/components/analytics/skills/GapsTab.tsx` | **create** — supply/demand gap analysis (from Marketplace) |
| `apps/web` | `src/components/analytics/skills/PeopleFinderTab.tsx` | **create** — AND/OR skill search (from Analytics) |
| `apps/web` | `src/components/analytics/skills/shared.tsx` | **create** — ProficiencyBadge, GapIndicator, constants |
| `apps/web` | `src/app/(app)/analytics/skills/page.tsx` | **edit** — render SkillsHub statt SkillsAnalytics |
| `apps/web` | `src/app/(app)/analytics/skill-marketplace/page.tsx` | **edit** — redirect to /analytics/skills |
| `apps/web` | `src/components/layout/AppShell.tsx` | **edit** — remove "Skill Marketplace" nav link |
| `packages/api` | `src/router/resource.ts` | **edit** — add unified getSkillsHub query |
### Task-Liste
- [ ] **Task 1:** Shared utilities extrahieren -> `skills/shared.tsx`
- `ProficiencyBadge`, `GapIndicator`, `PROFICIENCY_CLASSES`, `PROFICIENCY_LABELS`, `proficiencyClasses()`
- Einmal definieren, ueberall nutzen
- [ ] **Task 2:** API: neuen `getSkillsHub` Query -> `resource.ts`
- Kombiniert alle Daten in einem Call:
- `aggregated` (from getSkillsAnalytics)
- `searchResults` (from getSkillMarketplace)
- `gapData` (from getSkillMarketplace)
- `distribution` (from both, dedupliziert)
- `totalResources`, `totalSkillEntries`
- Alte Queries behalten (AI Assistant nutzt sie)
- [ ] **Task 3:** OverviewTab bauen -> `skills/OverviewTab.tsx`
- KPI Cards: Total Resources, Total Skills, Avg Proficiency, Skill Gaps Count
- Top 10 Skills Tabelle (sortierbar)
- Skill Distribution Chart (lazy-loaded)
- Quick filters: Category, Min Count
- [ ] **Task 4:** SearchTab bauen -> `skills/SearchTab.tsx`
- Skill name Suche (debounced)
- Min Proficiency Filter (1-5 Buttons)
- "Available in 30 days" Toggle
- Ergebnis-Tabelle: Resource, Chapter, Skill, Proficiency, Utilization, Available From
- Links zu `/resources/[id]`
- [ ] **Task 5:** GapsTab bauen -> `skills/GapsTab.tsx`
- Supply vs Demand Tabelle
- Supply/Demand Bar Visualisierung
- Gap Indicator (shortage/surplus/balanced)
- Sortierbar nach groesstem Gap
- Click auf Skill -> fuellt Search Tab
- [ ] **Task 6:** PeopleFinderTab bauen -> `skills/PeopleFinderTab.tsx`
- Multi-rule Builder: Skill + Min Proficiency pro Regel
- AND/OR Operator Toggle
- Chapter Filter
- Ergebnis-Tabelle mit Match Score
- XLSX Export Button
- [ ] **Task 7:** SkillsHub zusammenfuegen -> `SkillsHub.tsx`
- Tab Navigation (Overview, Search, Gaps, People Finder)
- Header mit KPI Summary + Export Button
- Tab State via URL search params
- Lazy-load Tabs fuer Performance
- [ ] **Task 8:** Routing + Navigation aktualisieren
- `/analytics/skills/page.tsx` -> rendert `<SkillsHub />`
- `/analytics/skill-marketplace/page.tsx` -> redirect zu `/analytics/skills?tab=search`
- AppShell: "Skill Marketplace" entfernen, "Skills Analytics" umbenennen zu "Skills Hub"
- [ ] **Task 9:** Dark Theme durchgaengig
- Alle Elemente mit `dark:` Varianten
- Konsistenz mit dem Rest der App
### Abhaengigkeiten
- Task 1 muss zuerst (shared utilities fuer alle Tabs)
- Task 2 kann parallel zu Task 1 (API aendern)
- Tasks 3-6 koennen parallel nach Task 1 (4 Tabs, unabhaengige Dateien)
- Task 7 benoetigt Tasks 3-6 (importiert alle Tabs)
- Task 8 benoetigt Task 7 (Routing zeigt auf neue Komponente)
- Task 9 kann parallel zu Task 8
### Akzeptanzkriterien
- [ ] `pnpm --filter @planarchy/web exec tsc --noEmit` — keine neuen Errors
- [ ] `/analytics/skills` zeigt die vereinte Seite mit 4 Tabs
- [ ] `/analytics/skill-marketplace` redirected zu `/analytics/skills?tab=search`
- [ ] Alle Features beider Seiten sind auf der neuen Seite verfuegbar
- [ ] Dark Theme funktioniert durchgehend
- [ ] Sidebar zeigt nur noch "Skills Hub" statt zwei Links
- [ ] XLSX Export funktioniert weiterhin
- [ ] People Finder AND/OR Suche funktioniert
- [ ] Skill Gap Heat Map mit Supply/Demand funktioniert
- [ ] Availability Filter (30 Tage) funktioniert
### Risiken & offene Fragen
- **API Performance:** Ein kombinierter Query koennte langsamer sein -> Loesung: Lazy-load per Tab, Query nur wenn Tab aktiv
- **URL State:** Aktiver Tab via `?tab=search` Query Param persistiert
- **Export:** Nur aktiver Tab exportierbar
- **Backwards-Kompatibilitaet:** AI Assistant Tools nutzen alte Queries -> behalten