trustos/docs/BUILD_PLAN.md

# TrustOS — Multi-Stage Build Plan

## Overview

TrustOS is a greenfield AI-powered cyber resilience platform for SMB and mid-market companies. The goal is to build a **living dashboard** that replaces static security reports with continuous, AI-translated risk visibility, remediation tracking, and board-ready proof of improvement.

The workspace is a clean slate — no application code exists yet. This plan takes the business strategy defined in [`readplan.txt`](readplan.txt) and breaks it into discrete, ordered build stages that produce a working, investable product.

**Approach:**
- Build from the inside out: data model → API → dashboard → integrations → intelligence layer
- Each stage produces something shippable and demonstrable
- Prioritize the Phase 1 Vault Audit delivery first — it is the monetizable wedge
- Defer AI automation and integrations until the manual workflow is validated

**Tech Stack (proposed):**
- **Frontend:** Next.js (React) + Tailwind CSS + shadcn/ui — fast to build premium dark UI
- **Backend API:** Python (FastAPI) — clean async API, great AI/ML ecosystem
- **Database:** PostgreSQL (via Supabase or self-hosted) — structured data, RLS for multi-tenant auth
- **AI Layer:** OpenAI or Anthropic API — risk translation, AI explainer, coach
- **Auth:** Supabase Auth or Clerk — multi-tenant, role-based (Executive / IT / Admin)
- **Deployment:** Docker Compose locally → cloud (Railway, Render, or VPS)

---

## Sub-Tasks

---

### Stage 1 — Project Scaffolding and Development Environment

**Intent:** Establish a working monorepo with frontend, backend, and database configured, running locally via Docker Compose. This is the foundation every other stage builds on.

**Expected Outcomes:**
- `git init` with organized directory structure (`/frontend`, `/backend`, `/infra`)
- Next.js app running at `localhost:3000` with dark TrustOS theme applied
- FastAPI backend running at `localhost:8000` with `/health` endpoint
- PostgreSQL database container running, accessible from backend
- `.env.example` files present for all secrets
- Docker Compose file that starts all three services with one command

**Todo List:**
1. Create monorepo structure: `/frontend`, `/backend`, `/infra`, `/docs`
2. Scaffold Next.js app inside `/frontend` with TypeScript and Tailwind CSS
3. Apply TrustOS brand theme (deep black background, titanium gray, sapphire blue accent, white text)
4. Scaffold FastAPI app inside `/backend` with a `/health` endpoint
5. Create `docker-compose.yml` in `/infra` for frontend, backend, and postgres services
6. Create `.env.example` for each service (db connection, API keys)
7. Confirm all three services start cleanly

**Relevant Context:**
- No existing code — full greenfield
- Theme: dark titanium, sapphire blue for healthy status, crimson only for urgent risk
- Must feel premium and calm, not alarmist

**Status:** `[ ] pending`

---

### Stage 2 — Data Model and Database Schema

**Intent:** Define the core database schema that represents the TrustOS data universe: clients, assets, findings, risk scores, remediation items, and users. A well-designed schema here prevents expensive migrations later.

**Expected Outcomes:**
- PostgreSQL schema with all core tables migrated and documented
- Seed script that populates one demo client with realistic mock data
- Backend can query the database and return JSON

**Todo List:**
1. Define `tenants` table (client organizations)
2. Define `users` table with roles: `executive`, `it_admin`, `trustos_admin`
3. Define `assets` table (domains, IPs, cloud resources, email accounts, executives)
4. Define `findings` table (vulnerability or exposure record linked to an asset)
5. Define `risk_scores` table (daily snapshot of overall and category scores per tenant)
6. Define `remediation_items` table (owner, status, due date, evidence, linked finding)
7. Define `audit_reports` table (Phase 1 Vault Audit container)
8. Write migration files (using Alembic for Python/FastAPI)
9. Write seed script with one demo tenant "Acme Corp" with realistic sample data

**Relevant Context:**
- Multi-tenant from day one — all tables must have `tenant_id`
- Findings need both technical details (CVE, CVSS) and AI-translated plain-English fields
- Risk score is 0–100, higher = safer (inverted from typical CVSS)

**Status:** `[ ] pending`

---

### Stage 3 — Authentication and Role-Based Access

**Intent:** Implement multi-tenant authentication with three roles: Executive (dashboard-only view), IT Admin (full technical detail + remediation), and TrustOS Admin (manages all tenants). This gate must exist before any dashboard work begins.

**Expected Outcomes:**
- Login page at `/login` with email + password
- JWT-based session with role stored in token
- Protected API routes — unauthenticated requests return 401
- Three demo users seeded: one per role for the demo tenant
- Frontend redirects to correct dashboard view based on role

**Todo List:**
1. Implement JWT auth in FastAPI (`/auth/login`, `/auth/me`, `/auth/logout`)
2. Add role middleware — decorator that checks role on protected routes
3. Build `/login` page in Next.js with TrustOS branding
4. Implement token storage (httpOnly cookie preferred)
5. Create auth context in React — exposes `user`, `role`, `tenantId`
6. Add route guards in Next.js that redirect unauthenticated users to `/login`
7. Seed three demo users (executive@acme.com, it@acme.com, admin@trustos.com)

**Relevant Context:**
- Executive role sees: risk score, Top 3 risks, trend, AI translations only — no raw technical data
- IT Admin role sees: full finding details, CVE IDs, remediation steps, evidence, logs
- TrustOS Admin: manages tenants, triggers scans, views all client data

**Status:** `[ ] pending`

---

### Stage 4 — Vault Dashboard (Executive View)

**Intent:** Build the core product moment — the executive-facing Vault dashboard. This is what a CEO sees when they log in. It must be visually premium, immediately understandable, and demonstrate TrustOS's value in the first 30 seconds.

**Expected Outcomes:**
- `/dashboard` route renders the Vault dashboard for the authenticated tenant
- Cyber Health Score displayed as a large dial/gauge (0–100, sapphire = healthy, crimson = critical)
- "Top 3 Risks" cards each showing: risk title, AI plain-English description, business impact level, remediation urgency
- Risk trend chart showing score improvement over past 90 days
- "Improved X% this month" callout if score improved
- All data sourced from API, not hardcoded

**Todo List:**
1. Build `RiskDial` component — circular gauge with sapphire/crimson gradient and score in center
2. Build `RiskCard` component — shows risk name, AI-translated impact sentence, urgency badge
3. Build `TrendChart` component — 90-day line chart of daily risk scores (use Recharts or Chart.js)
4. Build `ImprovementBadge` — shows "▲ Improved 8% this month" in sapphire
5. Assemble `/dashboard` page layout (dark background, card grid, TrustOS nav)
6. Wire `GET /api/dashboard/{tenant_id}` endpoint — returns score, Top 3 risks, trend data
7. Connect frontend to API with loading and error states
8. Ensure Executive role sees no raw CVE data anywhere on this view

**Relevant Context:**
- Risk cards must use plain English — no CVE IDs, no CVSS numbers visible to Executive role
- The Vault visual metaphor should feel premium: describe it as a "living room for security decisions"
- Each risk card has a "View Details" that navigates to the finding detail page

**Status:** `[ ] pending`

---

### Stage 5 — IT Admin View and Remediation Tracker

**Intent:** Build the technical layer of the dashboard for IT admins and security engineers. They need prioritized findings, technical details, remediation steps, asset ownership, and evidence — all in one place without switching tools.

**Expected Outcomes:**
- `/findings` route renders a sortable, filterable table of all active findings
- Each finding has a detail page with: technical description, CVE ID, CVSS score, AI explanation, remediation steps, asset link, owner assignment, status
- Remediation Tracker board (Kanban-style: Open → In Progress → Resolved → Verified)
- Status changes save to database and recalculate risk score
- "Mark as Resolved" requires an evidence upload or comment

**Todo List:**
1. Build `FindingsTable` component — sortable by severity, filterable by category, with status badges
2. Build `FindingDetail` page — two sections: technical (IT) and business impact (executive-friendly)
3. Build `RemediationBoard` — Kanban columns: Open, In Progress, Resolved, Verified
4. Wire `GET /api/findings` and `GET /api/findings/{id}` endpoints
5. Wire `PATCH /api/findings/{id}/status` — update status, log timestamp, require evidence note
6. Wire risk score recalculation trigger — when a finding moves to Verified, score updates
7. Add asset ownership field — assign findings to a team member
8. Build `EvidenceInput` component — text note or file reference to confirm fix

**Relevant Context:**
- Remediation Tracker is a key retention driver — it keeps IT teams inside TrustOS daily
- Verified status should require a human note, not just a click
- Score recalculation logic: each open Critical = -10pts, High = -5pts, Medium = -2pts (configurable)

**Status:** `[ ] pending`

---

### Stage 6 — AI Risk Translator

**Intent:** Integrate an LLM to automatically generate plain-English explanations for every finding. This is the "AI translates technical findings into business language" feature that is central to TrustOS's differentiation.

**Expected Outcomes:**
- Every finding in the database has an `ai_summary` field populated with plain-English translation
- AI summary follows the format: "What is this?" → "Why does it matter?" → "Business impact" → "Fix priority"
- Executive Risk Card uses the `ai_summary` — never raw CVE text
- AI Security Coach panel on Finding Detail page: interactive Q&A about any finding
- Estimated business impact tag (Low / Medium / High / Critical) generated by AI

**Todo List:**
1. Create `ai_translator` service in backend — wraps OpenAI/Anthropic API call
2. Write system prompt that instructs LLM to translate findings into business-grade plain English (no jargon, no CVE IDs, impact-first framing)
3. Add background job that processes any finding with no `ai_summary` and populates it
4. Add `GET /api/findings/{id}/ai-explain` endpoint — returns structured AI explanation
5. Build `AICoachPanel` component — chat-like UI on finding detail: user can ask "Can ransomware use this?" and get LLM answer in context
6. Store AI responses — do not re-call the API on every page load
7. Add `.env` config for `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`

**Relevant Context:**
- AI explanations must always be scoped to the specific finding — never generic
- Do not expose raw LLM output directly — always validate response shape before storing
- If AI is unavailable, fall back gracefully to the raw technical description

**Status:** `[ ] pending`

---

### Stage 7 — Digital Footprint Center

**Intent:** Build the OSINT / executive exposure module. This scans publicly available information about the client organization and its executives — leaked credentials, public email addresses, exposed domains, metadata. This is TrustOS's unique differentiator vs. pure technical scanners.

**Expected Outcomes:**
- `/footprint` route shows a Digital Footprint Center for the tenant
- Executive Exposure section: lists executives with their publicly found email addresses, leaked credentials (from breach DBs), public social profiles, WHOIS-linked info
- Domain/Asset Exposure section: exposed subdomains, misconfigured DNS, public cloud buckets, certificate issues
- All data stored as findings in the database, categorized as `type: "digital_footprint"`
- Manual entry mode first (admin enters data found manually); automated integration in a later stage

**Todo List:**
1. Add `digital_footprint` category to findings schema
2. Add `executives` table — links executives to a tenant with name, title, known public info
3. Build `FootprintDashboard` page — executive cards with exposure summary, domain exposure list
4. Build `ExecutiveExposureCard` — shows name, role, exposure count, worst exposure type
5. Build `AddExposureItem` form — TrustOS Admin manually logs a footprint finding for a tenant
6. Wire `GET /api/footprint/{tenant_id}` and `POST /api/footprint` endpoints
7. Connect findings from footprint to the main remediation tracker
8. Ensure privacy framing is correct: UI copy says "publicly available information that increases organizational risk" — not "surveillance of individuals"

**Relevant Context:**
- This is authorized, organization-scoped exposure monitoring only
- Phase 1 (manual entry): TrustOS analysts populate this during the Vault Audit
- Phase 2 (automated): integrate Have I Been Pwned API, Shodan, FullHunt, or similar
- Executives must be enrolled with explicit organizational authorization

**Status:** `[ ] pending`

---

### Stage 8 — Vault Audit Report Generation (Phase 1 Delivery)

**Intent:** Build the Phase 1 Vault Audit deliverable — the product that gets sold at $25K–$55K. A TrustOS admin can run a "Generate Vault Audit Report" action that produces a polished, shareable PDF and a locked dashboard view representing the point-in-time baseline.

**Expected Outcomes:**
- TrustOS Admin can trigger "Generate Vault Audit" for any tenant from the admin panel
- Audit report contains: Executive Summary, Cyber Health Score, Top 3 Risks, Digital Footprint Summary, Cloud Posture Summary, Remediation Roadmap with priorities
- Report exports as a PDF (branded TrustOS PDF with dark design)
- Dashboard shows "Audit Baseline: [Date]" badge — customer can compare current state vs. baseline
- Audit report is stored in `audit_reports` table and accessible at `/reports/{id}`

**Todo List:**
1. Build `/admin` panel — list of tenants, ability to trigger audit generation per tenant
2. Create `AuditReportBuilder` service — assembles all findings, scores, footprint data into an audit object
3. Build `AuditReportPage` — `/reports/{id}` renders the full audit as a styled web page
4. Integrate PDF export (use Puppeteer or `@react-pdf/renderer` for branded PDF generation)
5. Add "Audit Baseline" badge to dashboard — shows snapshot date and delta since baseline
6. Build audit summary email template — sent to tenant contact when audit is ready
7. Store generated PDF in file storage (local volume first, S3 later)

**Relevant Context:**
- The Vault Audit is the entry product — it must feel worth $25K–$55K
- The web-rendered version is the primary deliverable; PDF is for board meetings and insurance submissions
- Audit baseline is a locked snapshot — it does not change even as the live dashboard updates

**Status:** `[ ] pending`

---

### Stage 9 — Attack Path Visualization

**Intent:** Build the interactive attack path diagram that shows executives and IT teams how an attacker could move through their environment from internet to sensitive data. Visual, animated, understandable — turns "Port 443 vulnerable" into a story.

**Expected Outcomes:**
- Finding detail pages can show an associated attack path diagram
- Attack path is a directed graph: Internet → Entry Point → Pivot → Target (e.g., Customer Database)
- Nodes are labeled in plain English with risk level color coding
- AI generates the attack path narrative: "An attacker could use X to reach Y because Z"
- TrustOS Admin can define attack path chains manually in Phase 1; automated graph generation in Phase 2

**Todo List:**
1. Add `attack_paths` table — ordered list of nodes (asset or finding) that form a chain
2. Build `AttackPathGraph` component using React Flow or D3.js — directed graph with node/edge styling
3. Apply color coding: internet/attacker = crimson, pivot nodes = amber, target/data = sapphire
4. Add animated "flow" along attack path edges to show direction of attack
5. Wire `GET /api/attack-paths/{finding_id}` endpoint
6. Add AI narrative generation — LLM describes the path in plain English above the graph
7. Link attack paths from finding detail page and Executive Top 3 Risk cards

**Relevant Context:**
- Executives understand pictures — this is one of the highest-value visual moments in the product
- Keep Phase 1 simple: manually-defined linear chains. Automated graph traversal is Phase 3.
- Nodes should show: asset name, role in chain, plain-English label

**Status:** `[ ] pending`

---

### Stage 10 — Continuous Monitoring and Daily Assessment Engine

**Intent:** Build the backend engine that performs continuous automated checks against the tenant's authorized asset scope — new CVEs, certificate expiration, exposed services, cloud misconfigurations, domain changes. This is what makes TrustOS a monitoring subscription, not a one-time assessment.

**Expected Outcomes:**
- Scheduled daily job runs checks against each tenant's authorized asset list
- Checks include: certificate expiration (< 30 days), new CVE matching known tech stack, DNS/domain changes, cloud bucket public access, HIBP credential breach for known emails
- New findings are automatically created and surfaced on the dashboard
- Risk score updates nightly based on current finding state
- Tenants receive a weekly digest email: "What changed this week"

**Todo List:**
1. Create `scheduler` service (APScheduler or Celery Beat) that triggers daily assessment per tenant
2. Build `cert_checker` — checks SSL certificate expiration for all tenant domains
3. Build `cve_monitor` — queries NVD API for new CVEs matching known software/version data
4. Build `cloud_posture_checker` — checks for publicly accessible S3 buckets, open security groups (AWS SDK)
5. Build `breach_monitor` — checks Have I Been Pwned API for new credential exposures matching tenant emails
6. Build `risk_score_calculator` — nightly recalculation service, writes to `risk_scores` table
7. Build weekly digest email template and trigger
8. Add `authorized_assets` table — tenant scope definition, only scan what is explicitly authorized

**Relevant Context:**
- Authorization first — never scan assets not explicitly enrolled by the tenant
- Phase 1 uses basic external checks (cert expiry, OSINT, HIBP); Phase 2 adds cloud API integrations
- The daily check loop is what converts a one-time audit client into a $5K–$15K/month subscriber

**Status:** `[ ] pending`

---

### Stage 11 — Pitch Deck and Investor Materials (Digital Artifacts)

**Intent:** Produce the investor-facing digital deliverables described in the business plan: a web-rendered pitch deck (for sharing links), a one-page investor memo page, and exportable PDF versions. These are separate from the product and used for fundraising.

**Expected Outcomes:**
- `/pitch` route renders a scrollable, slide-by-slide investor pitch based on the 16-slide outline in readplan.txt
- Styled with the TrustOS brand: dark, sapphire, titanium, premium
- Each slide maps to the deck outline: Title, Problem, Why Now, Solution, Product, How It Works, Customer Wedge, Business Model, Pricing, Differentiation, GTM, Financials, Milestones, Funding Ask, Closing
- PDF export of the full pitch deck
- One-page investor memo at `/memo`

**Todo List:**
1. Create `/pitch` route — full-page scrollable slide deck layout
2. Build 16 slide components following the slide-by-slide build guide in readplan.txt
3. Build financial chart component for Year 1–3 revenue table
4. Build pricing ladder component for the four subscription tiers
5. Build comparison matrix component for differentiation slide
6. Apply consistent TrustOS brand (dark background, sapphire accents, clean sans-serif)
7. Add PDF export for full deck
8. Build `/memo` page with the two-page investor memo content from readplan.txt

**Relevant Context:**
- All content is defined in readplan.txt — no new copy needs to be written
- Pitch deck is for investor meetings — it must look polished enough to share before the product is live
- This can be built in parallel with Stage 8–10 if needed

**Status:** `[ ] pending`

---

## Implementation Order

```
Stage 1  → Scaffolding (foundation)
Stage 2  → Database schema
Stage 3  → Auth
Stage 4  → Executive dashboard (first demo-able moment)
Stage 5  → IT admin + remediation tracker
Stage 6  → AI risk translator (TrustOS differentiator)
Stage 7  → Digital footprint center
Stage 8  → Vault audit report generator (Phase 1 product)
Stage 9  → Attack path visualization
Stage 10 → Continuous monitoring engine (Phase 2 product)
Stage 11 → Pitch deck / investor materials (can run parallel to 8–10)
```

Stages 1–8 deliver the **Phase 1 Vault Audit** product — the $25K–$55K entry offer.  
Stages 9–10 complete the **Phase 2 monthly monitoring** subscription — $5K–$15K/month.  
Stage 11 supports the **fundraising process** in parallel.