# Leadership Intelligence Engine — Product & Technical Roadmap

## A) Phased Roadmap

### MVP (8–10 weeks)
- **User outcomes:** Leadership sees top execution/meeting risk signals; can run a meeting with Quick Brief; create/assign commitments; basic people timelines.
- **Feature scope:** Signals v0 (drift/stagnation/friction/meeting-decay with transparent math), Quick Brief generator, Meeting workspace (organizer/attendee), Commitments ledger with due dates/owners/escalation seed, People profiles (timeline entries, confidentiality tiers), Cast Mode for brief + signals, global search prototype, RBAC roles, tenant_id everywhere, immutable audit log, base layout refactor from `/template`.
- **Technical workstreams:** Laravel 11 foundation (PHP 8.2/8.3), multi-tenant middleware/scope, RBAC policies, audit listener; UI extraction of `/template` into `resources/views/layouts/app.blade.php` + partials/components + Cast layout; migrations/seeders for core tables and thresholds; cron-driven signal batch; cache for signal cards and search hints.
- **Risks:** Signal formula misfit, role leakage, Cast a11y gaps, Virtualmin PHP config drift.

### V1 (10–12 weeks)
- **User outcomes:** Leaders run recurring/ad-hoc meetings with auto Briefs; commitments tracked with evidence; signals more explainable.
- **Feature scope:** Meeting recurrence; one-click Brief pack (agenda+signals+commitments+strategy highlights+decisions); delegation + acknowledgment; recurring checkpoints; completion evidence uploads (outside web root); configurable signal weights/thresholds; Strategy module (Goals→Initiatives→Milestones→Measures); Newsletter repository (issues, tags, blocks, secure images); Org-health Cast route; global search across all modules.
- **Technical workstreams:** File storage outside web root with signed URLs; strategy builder templates; FTS indexes on key text; optional Redis cache; batch job surfacing stale strategy items; search indexer job.
- **Risks:** Storage path leakage, Brief quality, FTS performance on shared MariaDB.

### V2 (8–10 weeks)
- **User outcomes:** Trend and clustering intelligence; operational friction clusters; robust analytics.
- **Feature scope:** Trend analytics (30/90/365) for People/Signals/Strategy; recurrence clustering; meeting effectiveness decay scoring; overdue escalation rules; plan-builder templates (A3, 30-60-90); newsletter block library reuse; configurable signal views per role; exports.
- **Technical workstreams:** Materialized summary tables refreshed nightly; analytics views; CSV export with role filters; improved Cast keyboard shortcuts.
- **Risks:** Summary freshness drift; export performance; keyboard nav coverage.

### V3 (ongoing)
- **User outcomes:** Enterprise hardening and scale.
- **Feature scope:** Multi-tenant admin console; per-tenant thresholds; audit log viewer; SSO/SAML (optional); backup/restore automation; performance tuning; feature flags; observability.
- **Technical workstreams:** Read replicas (optional), query budgets, centralized logging, blue/green deploy pattern within Virtualmin limits.
- **Risks:** SSO complexity, replica lag, ops overhead.

## B) Information Architecture
- **Primary nav:** Signals | Briefings | Commitments | People | Strategy | Library | Search.
- **Template refactor:**
  - Create `resources/views/layouts/app.blade.php` using `/template` container/grid, header, sidebar, cards, tables, forms.
  - Partials: `partials/header.blade.php`, `partials/sidebar.blade.php`, `partials/breadcrumbs.blade.php`.
  - Components: card, table, badge/pill, modal, timeline, stat-block (retain `/template` class names).
  - Cast layout: `resources/views/layouts/cast.blade.php` (full-screen, no sidebar, large type, keyboard nav routes `/cast/brief/{id}`, `/cast/signals`, `/cast/org-health`).
  - Assets: move `/template/assets` to `public/assets` (or Vite pipeline), keep selectors stable; all pages extend layouts, never reference `/template` paths.

## C) Signals v0 Transparent Formulas
- **Execution Drift (0–100):** inputs last 30 days — % late initiatives (40%), stale cadence updates (35%), late commitments (25%); score = 100 − weighted sum; thresholds Red <60, Amber 60–79, Green ≥80.
- **Strategic Stagnation:** days since last milestone closed (50%), % measures without update (30%), decisions pending >14d (20%); rolling 60-day window.
- **Operational Friction Cluster:** count of incidents/coaching/warnings tagged to same process/team in rolling 30/90 windows; score = z-score vs org baseline; show top 5 clusters.
- **Meeting Effectiveness Decay:** agenda present, start/end on time, decisions recorded, follow-up commitments created, quick pulse score (weights 0.2 each); trigger when 3-meeting rolling avg <70.
- Every signal card shows inputs, weights, window, raw counts, calculation steps, contributing events, discussion prompts, resolve/snooze/assign actions.

## D) Database Entities & Indexing (MariaDB)
- **Tenancy/RBAC:** `tenants`, `roles`, `users(tenant_id, role_id)`, `permissions`, `role_permissions`.
- **Audit:** `audit_logs(tenant_id, user_id, entity, entity_id, action, before, after, ip, ua, created_at)` JSON before/after.
- **Signals:** `signals(tenant_id, type, title, score, status, window_start, window_end, weights json, inputs json, owner_id, resolved_at, snooze_until)`; `signal_events(signal_id, source, ref_type, ref_id, payload json)`.
- **Meetings/Briefs:** `meetings(tenant_id, title, type, recurrence, start_at, duration, organizer_id, cast_route, agenda json, brief json)`, `meeting_attendees`, `meeting_decisions`, `meeting_notes`, `briefs(meeting_id, generated_at, content json, version)`.
- **Commitments:** `commitments(tenant_id, source_type, source_id, title, owner_id, due_at, status, evidence_path, escalation_level, recurrence, ack_required, ack_at)`, `commitment_checkpoints(commitment_id, checkpoint_at, note)`.
- **People Intelligence:** `people(tenant_id, user_id?, name, role, supervisor_id, confidentiality_tier)`, `people_events(person_id, category, severity, description, occurred_at, created_by, visibility)`.
- **Strategy:** `goals`, `initiatives(goal_id)`, `milestones(initiative_id, due_at, status)`, `measures(initiative_id, name, target, actual, period_start, period_end)`, `cadence_updates(initiative_id, summary, status, created_at)`.
- **Library/Newsletter:** `newsletters(tenant_id, title, issue_date, tags, hero_image_path)`, `newsletter_blocks(newsletter_id, type, payload json)`.
- **Search:** `search_index(tenant_id, entity_type, entity_id, title, body, tags, updated_at)`.
- **Indexes:** composite `(tenant_id, status)` on workflow tables; date indexes on `due_at/occurred_at/start_at`; FTS on text columns (signals.title/body, commitments.title, people_events.description, newsletters.title/body); unique `(tenant_id, entity_type, entity_id)` on `search_index`.

## E) Deployment Plan (Ubuntu 22.04 + Virtualmin)
- Domain via Virtualmin; PHP-FPM 8.2/8.3; document root `public/`.
- Deploy: `git pull`, `.env` with DB/cache/mail, `composer install --no-dev`, `php artisan key:generate`.
- Permissions: web user owns `storage/`, `bootstrap/cache/`; uploads stored outside web root (`/home/.../uploads`), served via signed routes or controlled symlink.
- Migrations/seed: `php artisan migrate --seed` (roles, thresholds, sample weights).
- Cron: Virtualmin -> `* * * * * /usr/bin/php /home/.../public_html/artisan schedule:run`; nightly backups and signal recompute.
- TLS: Virtualmin Let’s Encrypt for domain + www, auto-renew.
- Backups: nightly `mysqldump` + rsync/s3copy of `/uploads`; retain 14/30 days; test restore monthly.

## F) Testing & Rollout
- **Unit:** Models, policies (RBAC, tenant scoping), signal calculators, date-window math.
- **Integration:** Signals → Brief → Commitment flow; file upload permissions; Cast rendering; search indexing.
- **Security:** authZ matrix by role, tenant isolation, signed URL access, audit log immutability, route rate limits.
- **Performance:** signal batch against ~50k rows; FTS latency checks.
- **Pilot:** stand up Tenant A (10–20 leaders), weekly feedback, feature flags for risky modules (Cast shortcuts, clustering).
- **Expansion:** add tenants gradually; monitor DB growth; consider read replica if >100 concurrent leaders; change calendar for releases.

## Technical Architecture Notes
- Framework: Laravel 11 chosen for RBAC/policies, migrations, queues (via cron), Blade templating to adapt `/template`, cache, testing.
- Multi-tenancy: single DB, `TenantScope` global, middleware sets tenant from domain/subdomain.
- Background jobs: artisan schedule for signals, summaries, backups; optional queue worker if Redis enabled.
- Caching: Redis preferred, file fallback; cache signal cards and search suggestions.
- Search: MariaDB FULLTEXT (InnoDB) on main text fields; incremental indexer populates `search_index`.
- File storage: outside web root, per-tenant; signed routes.