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 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.