trustos/README.md

# TrustOS

The AI Operating System for Cyber Resilience

[![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Next.js](https://img.shields.io/badge/Next.js-16-black.svg)](https://nextjs.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-blue.svg)](https://www.postgresql.org/)

TrustOS is an AI-powered cyber resilience platform for SMB and mid-market companies that need enterprise-grade security clarity without building an enterprise security team. The platform helps leadership teams understand their top cyber risks, prioritize fixes, track remediation, and prove improvement to customers, boards, insurers, and regulators.

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Quick Start](#quick-start)
- [Development Setup](#development-setup)
- [Configuration](#configuration)
- [Database Migrations](#database-migrations)
- [Testing](#testing)
- [Deployment](#deployment)
- [Documentation](#documentation)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

---

## Overview

TrustOS transforms cybersecurity from a technical burden into a business asset by:

- **Translating technical risks into business language** - AI-powered explanations that executives understand
- **Providing continuous visibility** - Living dashboard instead of static reports
- **Tracking remediation progress** - Clear ownership, deadlines, and proof of fixes
- **Proving improvement over time** - Measurable risk score trends for boards and insurers
- **Protecting executive exposure** - Digital footprint monitoring for leadership teams

### Dashboard Preview

The TrustOS Vault Dashboard provides executive-ready security visibility:

```
┌─────────────────────────────────────────────────────────────────────────┐
│ TrustOS Vault Dashboard                                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Cyber Resilience Overview                    Audit baseline: Jul 6    │
│                                                                          │
│  ┌──────────────────────┐  ┌─────────┬─────────┬─────────┬─────────┐  │
│  │   Cyber Health       │  │Critical │  High   │ Medium  │  Total  │  │
│  │      Score           │  │    2    │    5    │   12    │   19    │  │
│  │       89.2           │  └─────────┴─────────┴─────────┴─────────┘  │
│  │                      │                                              │
│  │  ↑ +2.5 pts         │  Risk Score — 90 Day Trend                   │
│  │   this month        │  ┌────────────────────────────────────────┐ │
│  │                      │  │ 100 ─ ╱╲                              │ │
│  └──────────────────────┘  │  90 ─╱  ╲  ╱╲  ╱╲                     │ │
│                            │  80 ────  ╱──╲╱  ╲╱╲  ╱─ Current: 89.2 │
│                            │  70 ─────────────────────────          │ │
│                            │     Jun      Jul      Aug              │ │
│                            └────────────────────────────────────────┘ │
│                                                                        │
│  Top Risks Requiring Your Attention                 View all findings →│
│                                                                        │
│  ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐│
│  │🔴 CRITICAL        │ │🟠 HIGH             │ │🟠 HIGH             ││
│  │                    │ │                    │ │                    ││
│  │Internet-accessible│ │5 executive email   │ │S3 bucket publicly  ││
│  │admin panel with    │ │accounts found in   │ │accessible with     ││
│  │no authentication   │ │breach database     │ │customer files      ││
│  │                    │ │                    │ │                    ││
│  │An attacker could   │ │Attackers could     │ │This constitutes a  ││
│  │gain full control   │ │access email, cloud │ │data breach. Exposure││
│  │of your platform,   │ │systems, and data   │ │of customer PII may ││
│  │access all customer │ │— enabling targeted │ │trigger regulatory  ││
│  │data, and disrupt   │ │phishing and wire   │ │penalties.          ││
│  │operations.         │ │fraud.              │ │                    ││
│  │                    │ │                    │ │                    ││
│  │Fix Priority:       │ │Fix Priority:       │ │Fix Priority:       ││
│  │URGENT              │ │URGENT              │ │URGENT              ││
│  └────────────────────┘ └────────────────────┘ └────────────────────┘│
│                                                                        │
└─────────────────────────────────────────────────────────────────────────┘
```

**Current Status**: 
- Cyber Health Score: **89.2** (healthy baseline)
- Open Critical Issues: **2**
- Open High Issues: **5**
- 30-day Improvement: **+2.5 points** 📈
- Demo Data: **6 findings** with AI-translated business impact

### System Architecture Overview

```mermaid
graph TB
    subgraph Client["Client Layer"]
        Browser[Web Browser]
    end
    
    subgraph Frontend["Frontend Layer"]
        NextJS[Next.js 16 + TypeScript]
        Tailwind[Tailwind CSS + shadcn/ui]
    end
    
    subgraph API["API Layer"]
        FastAPI[FastAPI + Pydantic]
        Auth[Authentication & Authorization]
        Services[Business Logic Services]
        AI[AI Integration Layer]
    end
    
    subgraph Database["Database Layer"]
        PostgreSQL[(PostgreSQL 16)]
        Migrations[Alembic Migrations]
    end
    
    subgraph External["External Services"]
        OpenAI[OpenAI API]
        Anthropic[Anthropic API]
        HIBP[HIBP API]
        NVD[NVD API]
    end
    
    Browser -->|HTTPS| NextJS
    NextJS -->|REST API| FastAPI
    FastAPI --> Auth
    FastAPI --> Services
    Services --> AI
    Services --> PostgreSQL
    AI --> OpenAI
    AI --> Anthropic
    Services --> HIBP
    Services --> NVD
    PostgreSQL --> Migrations
    
    style Frontend fill:#e1f5ff
    style API fill:#fff4e1
    style Database fill:#e8f5e9
    style External fill:#f3e5f5
```

### Business Model

```mermaid
graph LR
    subgraph Phase1["Phase 1: Vault Audit"]
        Audit[One-time Assessment<br/>$25K-$95K]
        Dashboard[Interactive Dashboard]
        Report[Audit Report]
    end
    
    subgraph Phase2["Phase 2: Monthly Monitoring"]
        Monitor[Continuous Monitoring<br/>$5K-$15K/month]
        Daily[Daily Assessments]
        Alerts[Automated Alerts]
    end
    
    subgraph Phase3["Phase 3: Full Platform"]
        Platform[Full Platform<br/>$180K-$900K/year]
        AI[AI Security Coach]
        Advanced[Advanced Integrations]
    end
    
    Audit --> Dashboard
    Audit --> Report
    Audit --> Monitor
    Monitor --> Daily
    Monitor --> Alerts
    Monitor --> Platform
    Platform --> AI
    Platform --> Advanced
    
    style Phase1 fill:#e3f2fd
    style Phase2 fill:#fff3e0
    style Phase3 fill:#f3e5f5
```

- **Phase 1: Vault Audit** ($25K–$95K) - One-time comprehensive assessment with interactive dashboard
- **Phase 2: Monthly Monitoring** ($5K–$15K/month) - Continuous monitoring and daily risk updates
- **Phase 3: Full Platform** ($180K–$900K/year) - Complete cyber resilience operating system

---

## For Executives

### Business Value

TrustOS provides executives with:

- **Clear Risk Visibility**: Understand your cyber posture in minutes, not days
- **Board-Ready Reporting**: Professional reports for boards, insurers, and regulators
- **Measurable Improvement**: Track risk score trends to prove security investments
- **Executive Protection**: Monitor digital footprint of leadership team
- **Compliance Support**: Demonstrate due diligence to customers and auditors

### Key Metrics Tracked

| Metric | Description | Target |
|--------|-------------|--------|
| Cyber Health Score | Overall security posture (0-100) | 80+ |
| Critical Findings | High-priority vulnerabilities | 0 |
| Remediation Rate | Issues resolved per month | 90%+ |
| Risk Trend | 90-day score change | Positive |

### ROI Calculator

**Before TrustOS**:
- Annual security consulting: $50,000
- Breach risk: 15% chance × $200,000 avg cost = $30,000 expected loss
- Total: $80,000/year

**After TrustOS**:
- TrustOS subscription: $288,000/year
- Breach risk reduction: 5% chance × $200,000 = $10,000 expected loss
- Insurance premium savings: $15,000/year
- Net cost: $263,000/year

**Value**: Professional-grade security with measurable ROI

---

## For Developers

### Tech Stack Details

| Layer | Technology | Purpose |
|-------|-----------|---------|
| Frontend | Next.js 16 | React framework with App Router |
| Frontend | TypeScript | Type-safe JavaScript |
| Frontend | Tailwind CSS | Utility-first CSS framework |
| Frontend | shadcn/ui | Pre-built UI components |
| Backend | FastAPI | Modern Python web framework |
| Backend | SQLAlchemy 2.0 | Async ORM for database |
| Backend | PostgreSQL | Relational database |
| Backend | Alembic | Database migration tool |
| AI | OpenAI/Anthropic | LLM for risk translation |
| Infra | Docker | Containerization |
| Infra | Docker Compose | Multi-container orchestration |

### Development Workflow

```mermaid
graph TD
    Start[Start Development] --> Clone[Clone Repository]
    Clone --> SetupEnv[Setup Environment]
    SetupEnv --> BackendSetup[Backend Setup]
    SetupEnv --> FrontendSetup[Frontend Setup]
    BackendSetup --> InstallDeps[Install Dependencies]
    FrontendSetup --> NPMInstall[npm install]
    InstallDeps --> ConfigEnv[Configure .env]
    NPMInstall --> ConfigFrontend[Configure .env.local]
    ConfigEnv --> SeedDB[Seed Database]
    ConfigFrontend --> StartDev[Start Dev Servers]
    SeedDB --> StartDev
    StartDev --> DevLoop[Development Loop]
    DevLoop --> Test[Write Tests]
    Test --> Commit[Commit Changes]
    Commit --> Push[Push to Git]
    
    style Start fill:#e8f5e9
    style DevLoop fill:#fff3e0
    style Test fill:#e3f2fd
```

### Key Design Patterns

- **Repository Pattern**: Database access through service layer
- **Dependency Injection**: FastAPI dependencies for database, auth
- **Async/Await**: Non-blocking I/O throughout
- **JWT Authentication**: Stateless token-based auth
- **Multi-Tenant**: Tenant isolation at all layers
- **RBAC**: Role-based access control

### API Response Times

| Endpoint | Expected Response Time | SLA |
|----------|----------------------|-----|
| Login | < 500ms | 99.9% |
| Dashboard | < 1s | 99.5% |
| Findings List | < 500ms | 99.5% |
| Finding Detail | < 300ms | 99.9% |
| Report Generation | < 30s | 95% |

---

## Features

### Current Implementation (Phase 1)

#### Executive Dashboard
- **Cyber Health Score** - 0–100 gauge showing overall security posture
- **Top 3 Risks** - AI-translated business impact for critical vulnerabilities
- **Risk Trend Visualization** - 90-day history showing improvement or decline
- **Baseline Comparison** - Compare current state against audit baseline

#### Findings Management
- **Comprehensive Finding Database** - CVEs, cloud misconfigurations, credential exposures
- **AI Risk Translation** - Plain-English explanations for every technical finding
- **Remediation Tracking** - Kanban-style board: Open → In Progress → Resolved → Verified
- **Asset Ownership** - Assign findings to team members with due dates

#### Digital Footprint Center
- **Executive Exposure Monitoring** - Publicly available information about leadership
- **Domain/Asset Exposure** - Exposed subdomains, misconfigured DNS, certificate issues
- **Breach Intelligence** - Leaked credentials from public breach databases

#### Authentication & Access Control
- **Multi-Tenant Architecture** - Complete data isolation between organizations
- **Role-Based Access Control** - Executive, IT Admin, TrustOS Admin roles
- **JWT Authentication** - Secure token-based sessions

#### Reporting
- **Vault Audit Reports** - Branded PDF exports with executive summaries
- **Baseline Snapshots** - Point-in-time assessments for comparison
- **Board-Ready Formatting** - Professional layouts for stakeholders

### Planned Features (Phase 2 & 3)

- **Continuous Monitoring Engine** - Daily automated assessments
- **Attack Path Visualization** - Interactive diagrams showing attack vectors
- **AI Security Coach** - Interactive Q&A about specific findings
- **Executive Protection Services** - Enhanced monitoring for leadership
- **Advanced Integrations** - Cloud APIs, SIEM connectors, threat intelligence feeds

---

## Architecture

TrustOS follows a modern, scalable architecture designed for security and performance:

```
┌─────────────────────────────────────────────────────────────────┐
│                         Frontend Layer                          │
│  Next.js 16 + TypeScript + Tailwind CSS + shadcn/ui             │
│  - Executive Dashboard                                           │
│  - Findings Management                                            │
│  - Digital Footprint Center                                      │
│  - Report Generation                                             │
└────────────────────┬────────────────────────────────────────────┘
                     │ HTTPS / REST API
┌────────────────────▼────────────────────────────────────────────┐
│                         API Layer                                │
│  FastAPI + Pydantic + SQLAlchemy 2.0                             │
│  - Authentication & Authorization                               │
│  - Business Logic Services                                      │
│  - AI Integration Layer                                          │
│  - Risk Calculator                                               │
│  - Report Generator                                              │
└────────────────────┬────────────────────────────────────────────┘
                     │ Async PostgreSQL
┌────────────────────▼────────────────────────────────────────────┐
│                      Database Layer                             │
│  PostgreSQL 16 + Alembic Migrations                              │
│  - Tenants, Users, Assets, Findings                             │
│  - Risk Scores, Attack Paths, Audit Reports                      │
│  - Executives, Authorized Assets                                │
└─────────────────────────────────────────────────────────────────┘

External Integrations:
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ OpenAI API   │  │ Anthropic API│  │ HIBP API     │  │ NVD API      │
│ (AI Translation)│ (AI Coach)   │  │ (Breach Data)│  │ (CVE Data)   │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
```

### Key Design Principles

- **Authorization First** - Only scan explicitly authorized assets
- **Multi-Tenant Isolation** - Complete data separation at database and API levels
- **Privacy by Design** - Executive monitoring requires explicit organizational authorization
- **AI-Augmented, Not AI-Dependent** - Graceful degradation when AI is unavailable
- **Audit Trail** - All changes tracked with timestamps and user attribution

---

## Tech Stack

### Frontend
- **Framework**: Next.js 16 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **Components**: shadcn/ui (Radix UI primitives)
- **Charts**: Recharts
- **State Management**: React Context + Hooks
- **HTTP Client**: Native fetch with custom API wrapper

### Backend
- **Framework**: FastAPI
- **Language**: Python 3.10+
- **ORM**: SQLAlchemy 2.0 (async)
- **Database**: PostgreSQL 16
- **Authentication**: JWT (python-jose)
- **Password Hashing**: Passlib (bcrypt)
- **Task Queue**: Celery + Redis (planned)
- **Scheduler**: APScheduler

### AI/ML
- **Primary Provider**: OpenAI GPT-4o-mini
- **Alternative**: Anthropic Claude 3 Haiku
- **Use Cases**: Risk translation, attack path generation, security coach

### Infrastructure
- **Containerization**: Docker + Docker Compose
- **Reverse Proxy**: Nginx (production)
- **Process Manager**: Uvicorn (ASGI server)
- **Database Migrations**: Alembic
- **PDF Generation**: WeasyPrint + Jinja2

---

## Project Structure

```
trustos/
├── frontend/                      # Next.js frontend application
│   ├── src/
│   │   ├── app/                   # Next.js App Router pages
│   │   │   ├── dashboard/         # Executive dashboard
│   │   │   ├── findings/         # Findings management
│   │   │   ├── login/            # Authentication
│   │   │   └── page.tsx          # Root redirect
│   │   ├── components/           # Reusable React components
│   │   ├── hooks/                # Custom React hooks
│   │   │   └── useAuth.ts        # Authentication state
│   │   └── lib/                  # Utility functions
│   │       └── api.ts            # API client
│   ├── public/                   # Static assets
│   ├── package.json              # Dependencies
│   ├── tailwind.config.ts        # Tailwind configuration
│   ├── tsconfig.json             # TypeScript configuration
│   └── next.config.js            # Next.js configuration
│
├── backend/                       # FastAPI backend application
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/           # API endpoints
│   │   │       ├── auth.py       # Authentication
│   │   │       ├── dashboard.py  # Dashboard data
│   │   │       ├── findings.py   # Findings CRUD
│   │   │       ├── reports.py    # Audit reports
│   │   │       ├── attack_paths.py # Attack visualization
│   │   │       ├── footprint.py  # Digital footprint
│   │   │       └── ai.py         # AI endpoints
│   │   ├── core/
│   │   │   ├── config.py         # Configuration settings
│   │   │   └── security.py       # Auth & security utilities
│   │   ├── db/
│   │   │   └── session.py        # Database session
│   │   ├── models/
│   │   │   └── models.py         # SQLAlchemy ORM models
│   │   ├── schemas/
│   │   │   └── schemas.py        # Pydantic schemas
│   │   ├── services/
│   │   │   ├── ai_translator.py  # AI translation service
│   │   │   ├── risk_calculator.py # Risk scoring
│   │   │   └── report_generator.py # PDF generation
│   │   ├── workers/              # Background tasks
│   │   └── main.py               # FastAPI application entry
│   ├── alembic/                  # Database migrations
│   │   ├── versions/             # Migration files
│   │   ├── env.py                # Alembic environment
│   │   └── script.py.mako        # Migration template
│   ├── tests/                    # Backend tests
│   ├── requirements.txt          # Python dependencies
│   ├── seed.py                   # Demo data seeding
│   ├── alembic.ini               # Alembic configuration
│   └── .env.example              # Environment template
│
├── infra/                         # Infrastructure configuration
│   ├── docker-compose.yml        # Local development stack
│   ├── Dockerfile.backend        # Backend container
│   └── Dockerfile.frontend       # Frontend container
│
├── docs/                          # Additional documentation
│   ├── ARCHITECTURE.md           # Detailed architecture docs
│   ├── API.md                    # API reference
│   ├── DEPLOYMENT.md             # Deployment guide
│   └── CONTRIBUTING.md          # Contribution guidelines
│
├── trustos-plan.md               # Detailed build plan and stages
├── README.md                     # This file
└── .gitignore                    # Git ignore rules
```

---

## Quick Start

### Setup Flow

```mermaid
graph LR
    A[Clone Repo] --> B[Configure .env]
    B --> C[Start Docker Compose]
    C --> D[Seed Database]
    D --> E[Access Application]
    
    style A fill:#e8f5e9
    style B fill:#fff3e0
    style C fill:#e3f2fd
    style D fill:#f3e5f5
    style E fill:#fce4ec
```

### Prerequisites

Ensure you have the following installed:

- **Docker** 20.10+ and **Docker Compose** 2.0+
- **Git** for version control
- **Python** 3.10+ (for local development)
- **Node.js** 18+ and **npm** 9+ (for local development)
- **PostgreSQL** 16+ (if not using Docker)

### Docker Compose Setup (Recommended)

This is the fastest way to get TrustOS running locally with all dependencies.

1. **Clone the repository**
   ```bash
   git clone https://gitea.thetempleofdoom.com/drjones/trustos.git
   cd trustos
   ```

2. **Configure environment variables**
   ```bash
   cp backend/.env.example backend/.env
   ```
   
   Edit `backend/.env` and configure at minimum:
   ```bash
   # Database (Docker Compose handles this)
   DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@postgres:5432/trustos
   SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@postgres:5432/trustos
   
   # Auth - CHANGE THIS IN PRODUCTION
   SECRET_KEY=changeme-use-openssl-rand-hex-32-in-production
   
   # AI - Optional for demo (features work without it)
   OPENAI_API_KEY=sk-...
   AI_PROVIDER=openai
   ```

3. **Start all services**
   ```bash
   cd infra
   docker-compose up --build
   ```
   
   This will start:
   - PostgreSQL database on port 5432
   - FastAPI backend on port 8000
   - Next.js frontend on port 3000

4. **Initialize the database with demo data**
   
   In a new terminal:
   ```bash
   cd backend
   docker-compose exec backend python seed.py
   ```

5. **Access the application**
   - **Frontend**: http://localhost:3000
   - **Backend API**: http://localhost:8000
   - **API Documentation**: http://localhost:8000/docs
   - **ReDoc Documentation**: http://localhost:8000/redoc

### Demo Credentials

The seed script creates a demo tenant "Acme Corp" with three users:

| Role | Email | Password |
|------|-------|----------|
| Executive (CEO) | executive@acmecorp.io | TrustOS2024! |
| IT Admin | it@acmecorp.io | TrustOS2024! |
| TrustOS Admin | admin@trustos.com | TrustOS-Admin-2024! |

### Stopping the Services

```bash
cd infra
docker-compose down
```

To remove volumes (delete database data):
```bash
docker-compose down -v
```

---

## Development Setup

For active development, it's often easier to run services natively rather than in Docker.

### Backend Setup

1. **Create a Python virtual environment**
   ```bash
   cd backend
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```
   
   Minimum required for local development:
   ```bash
   DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@localhost:5432/trustos
   SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@localhost:5432/trustos
   SECRET_KEY=dev-secret-key-change-in-production
   ```

4. **Set up PostgreSQL**
   
   Using Docker for just the database:
   ```bash
   docker run --name trustos-postgres \
     -e POSTGRES_USER=trustos \
     -e POSTGRES_PASSWORD=trustos_dev \
     -e POSTGRES_DB=trustos \
     -p 5432:5432 \
     -d postgres:16
   ```

5. **Initialize the database**
   ```bash
   python seed.py
   ```

6. **Run the backend server**
   ```bash
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   ```

   The API will be available at http://localhost:8000

### Frontend Setup

1. **Install dependencies**
   ```bash
   cd frontend
   npm install
   ```

2. **Configure environment variables**
   
   Create `.env.local` (this file is git-ignored):
   ```bash
   NEXT_PUBLIC_API_URL=http://localhost:8000
   ```

3. **Run the development server**
   ```bash
   npm run dev
   ```

   The frontend will be available at http://localhost:3000

### Development Workflow

1. Make changes to frontend or backend code
2. Backend auto-reloads with `--reload` flag
3. Frontend hot-reloads automatically
4. Access API docs at http://localhost:8000/docs to test endpoints

---

## Configuration

### Backend Environment Variables

See `backend/.env.example` for the complete list. Key variables:

#### Database
```bash
DATABASE_URL=postgresql+asyncpg://trustos:trustos_dev@postgres:5432/trustos
SYNC_DATABASE_URL=postgresql://trustos:trustos_dev@postgres:5432/trustos
```

#### Authentication
```bash
# IMPORTANT: Generate a secure random key in production using: openssl rand -hex 32
# Never use the default value in production environments
SECRET_KEY=changeme-use-openssl-rand-hex-32-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=480
```

#### AI Configuration
```bash
AI_PROVIDER=openai  # or 'anthropic'
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

#### External APIs
```bash
HIBP_API_KEY=...  # Have I Been Pwned for breach data
NVD_API_KEY=...   # National Vulnerability Database
```

#### Storage
```bash
STORAGE_PATH=/app/storage  # Path for PDF reports and uploads
```

#### Email (Optional)
```bash
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=...
SMTP_PASSWORD=...
SMTP_FROM=noreply@trustos.com
```

### Frontend Environment Variables

```bash
NEXT_PUBLIC_API_URL=http://localhost:8000
```

For production:
```bash
NEXT_PUBLIC_API_URL=https://api.trustos.com
```

---

## Database Migrations

TrustOS uses Alembic for database schema management. In development, tables are auto-created on startup for convenience. For production, always use migrations.

### Creating a New Migration

```bash
cd backend
alembic revision --autogenerate -m "Description of changes"
```

### Applying Migrations

```bash
alembic upgrade head
```

### Rolling Back

```bash
alembic downgrade -1
```

### Migration Best Practices

- Always review auto-generated migrations before committing
- Write descriptive migration messages
- Test migrations on a copy of production data
- Never modify existing migrations after they're applied

---

## Testing

### Backend Tests

```bash
cd backend
pytest
```

Run with coverage:
```bash
pytest --cov=app --cov-report=html
```

Run specific test file:
```bash
pytest tests/test_auth.py
```

### Frontend Tests

```bash
cd frontend
npm test
```

Run with coverage:
```bash
npm test -- --coverage
```

### Manual Testing

1. **API Testing**: Use the interactive Swagger UI at http://localhost:8000/docs
2. **Frontend Testing**: Log in with demo credentials and explore features
3. **Integration Testing**: Use Docker Compose for full-stack testing

---

## Deployment

### Production Checklist

Before deploying to production, ensure you have:

- [ ] Changed `SECRET_KEY` to a cryptographically secure random value (`openssl rand -hex 32`)
- [ ] Set strong database passwords
- [ ] Configured production database (Supabase, RDS, Neon, etc.)
- [ ] Enabled HTTPS/TLS with valid certificates
- [ ] Set up proper CORS origins (restrict to your domain)
- [ ] Configured AI API keys with appropriate rate limits
- [ ] Set up logging and monitoring (Sentry, Datadog, etc.)
- [ ] Enabled automated database backups
- [ ] Reviewed and updated security headers
- [ ] Run Alembic migrations instead of auto-create tables
- [ ] Configured environment-specific variables
- [ ] Set up CI/CD pipeline
- [ ] Configured error tracking
- [ ] Set up health check endpoints

### Deployment Options

#### Option 1: Railway (Recommended for simplicity)

Railway supports both PostgreSQL and containerized apps.

1. Connect your GitHub repository to Railway
2. Create a PostgreSQL service
3. Create a backend service (Dockerfile)
4. Create a frontend service (Dockerfile)
5. Add environment variables in Railway dashboard
6. Deploy

#### Option 2: Render

Render offers PostgreSQL and container hosting.

1. Create a PostgreSQL database on Render
2. Connect backend to Render PostgreSQL
3. Deploy backend as a web service
4. Deploy frontend as a static site
5. Configure environment variables

#### Option 3: VPS (DigitalOcean, Linode, AWS EC2)

For full control:

1. Set up a VPS with Ubuntu 22.04+
2. Install Docker and Docker Compose
3. Clone repository
4. Configure production `.env` file
5. Use nginx as reverse proxy
6. Set up SSL with Let's Encrypt
7. Run `docker-compose up -d`

See `docs/DEPLOYMENT.md` for detailed VPS deployment instructions.

### Environment-Specific Configurations

**Development**:
- Auto-create tables on startup
- Debug mode enabled
- CORS allowed from localhost
- Logging to console

**Production**:
- Use Alembic migrations
- Debug mode disabled
- CORS restricted to specific domains
- Logging to file/external service
- Rate limiting enabled

---

## Documentation

### Project Documentation

- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Detailed system architecture, data flow, and design decisions
- **[API.md](docs/API.md)** - Complete API reference with examples
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Production deployment guides
- **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** - Contribution guidelines and development standards

### Business Documentation

- **[BUILD_PLAN.md](docs/BUILD_PLAN.md)** - Multi-stage build plan and implementation roadmap
- **[BUSINESS_PLAN.md](docs/BUSINESS_PLAN.md)** - Complete business plan, investor memo, and pitch deck outline

### API Documentation

When the backend is running, interactive API documentation is available:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

---

## Security

### Security Architecture

TrustOS implements defense-in-depth security:

1. **Authentication**: JWT-based stateless authentication
2. **Authorization**: Role-based access control (RBAC)
3. **Multi-Tenant Isolation**: Database-level tenant separation
4. **Input Validation**: Pydantic schemas for all inputs
5. **SQL Injection Prevention**: SQLAlchemy ORM with parameterized queries
6. **XSS Prevention**: React's built-in escaping
7. **CSRF Protection**: SameSite cookie attributes
8. **Secure Headers**: CORS, CSP, HSTS configured

### Security Best Practices

- Never commit `.env` files or secrets to git
- Use strong, unique passwords for all services
- Rotate API keys regularly
- Enable audit logging in production
- Implement rate limiting on public endpoints
- Use HTTPS everywhere
- Keep dependencies updated
- Regular security audits
- Principle of least privilege for database users

### Data Privacy

- Executive monitoring requires explicit organizational authorization
- All data is tenant-isolated
- No cross-tenant data access
- Audit trail for all data access
- GDPR-compliant data handling practices

---

## Troubleshooting

### Troubleshooting Flow

```mermaid
graph TD
    Start[Issue Detected] --> CheckLogs{Check Logs}
    CheckLogs -->|Error Message| IdentifyError[Identify Error Type]
    CheckLogs -->|No Error| CheckServices{Check Services}
    
    IdentifyError --> DBError{Database Error?}
    IdentifyError --> APIError{API Error?}
    IdentifyError --> FrontError{Frontend Error?}
    
    DBError -->|Yes| CheckDB[Check DB Connection]
    DBError -->|No| APIError
    
    APIError -->|Yes| CheckAuth[Check Auth Token]
    APIError -->|No| FrontError
    
    FrontError -->|Yes| CheckEnv[Check .env.local]
    FrontError -->|No| CheckServices
    
    CheckDB --> FixDB[Fix DATABASE_URL]
    CheckAuth --> FixAuth[Refresh Token]
    CheckEnv --> FixEnv[Set NEXT_PUBLIC_API_URL]
    
    CheckServices -->|All Running| Restart[Restart Services]
    CheckServices -->|Not Running| Start[Start Services]
    
    FixDB --> Test
    FixAuth --> Test[Test Fix]
    FixEnv --> Test
    Restart --> Test
    Start --> Test
    
    Test -->|Fixed| Done[Issue Resolved]
    Test -->|Not Fixed| Support[Contact Support]
    
    style Start fill:#fce4ec
    style Done fill:#e8f5e9
    style Support fill:#fff3e0
```

### Common Issues

#### Backend won't start

**Problem**: `ModuleNotFoundError: No module named 'app'`

**Solution**: Ensure you're running from the backend directory:
```bash
cd backend
uvicorn app.main:app --reload
```

#### Database connection errors

**Problem**: `could not connect to server: Connection refused`

**Solution**: 
- Ensure PostgreSQL is running
- Check DATABASE_URL in `.env`
- Verify database credentials

#### Frontend can't connect to backend

**Problem**: Network errors in browser console

**Solution**:
- Check `NEXT_PUBLIC_API_URL` in frontend `.env.local`
- Ensure backend is running on the expected port
- Check CORS configuration in backend

#### AI features not working

**Problem**: AI translations return empty or errors

**Solution**:
- Verify `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is set
- Check API key has credits/quota
- Review backend logs for specific error messages
- Features work without AI, just with raw technical data

#### Migration errors

**Problem**: `alembic.util.exc.CommandError: Target database is not up to date`

**Solution**:
```bash
alembic upgrade head
```

If that fails, you may need to resolve migration conflicts manually.

### Getting Help

1. Check the logs: `docker-compose logs` or backend console output
2. Review API documentation at `/docs`
3. Check environment variable configuration
4. Verify all services are running
5. For persistent issues, contact the TrustOS development team

---

## Contributing

We welcome contributions to TrustOS! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

### Development Workflow

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Write tests for new functionality
5. Ensure all tests pass: `pytest` and `npm test`
6. Commit your changes: `git commit -m 'Add amazing feature'`
7. Push to the branch: `git push origin feature/amazing-feature`
8. Open a Pull Request

### Code Style

- **Python**: Follow PEP 8, use black for formatting
- **TypeScript**: Follow ESLint rules, use Prettier for formatting
- **Commits**: Use conventional commit messages
- **Documentation**: Update docs for any user-facing changes

---

## License

Proprietary - All rights reserved

TrustOS is a commercial product. All rights are reserved by the copyright holders. Unauthorized copying, distribution, or use of this software is strictly prohibited.

---

## Support

For technical issues, questions, or partnership inquiries:

- **Email**: support@trustos.com
- **Documentation**: https://docs.trustos.com
- **Status Page**: https://status.trustos.com

---

## Acknowledgments

TrustOS is built with open-source technologies:

- [Next.js](https://nextjs.org/) - React framework
- [FastAPI](https://fastapi.tiangolo.com/) - Python web framework
- [Tailwind CSS](https://tailwindcss.com/) - CSS framework
- [shadcn/ui](https://ui.shadcn.com/) - UI components
- [PostgreSQL](https://www.postgresql.org/) - Database
- [OpenAI](https://openai.com/) - AI services
- [Anthropic](https://www.anthropic.com/) - AI services

---

**TrustOS — The AI Operating System for Cyber Resilience**

*Making cyber resilience simple, continuous, and understandable for every growing company.*

## Architecture

TrustOS is a full-stack application with the following components:

- **Frontend**: Next.js 16 (React) + TypeScript + Tailwind CSS + shadcn/ui
- **Backend**: Python (FastAPI) + SQLAlchemy 2.0 + Async PostgreSQL
- **Database**: PostgreSQL 16
- **AI Layer**: OpenAI GPT-4o-mini or Anthropic Claude 3 Haiku
- **Deployment**: Docker Compose (local), Railway/Render/VPS (production)

## Project Structure

```
trustos/
├── frontend/          # Next.js frontend application
│   ├── src/
│   │   ├── app/      # Next.js App Router pages
│   │   ├── components/  # React components
│   │   ├── hooks/    # Custom React hooks
│   │   └── lib/      # Utility functions and API client
│   ├── package.json
│   └── tailwind.config.ts
├── backend/           # FastAPI backend application
│   ├── app/
│   │   ├── api/routes/   # API endpoints
│   │   ├── core/         # Configuration and security
│   │   ├── db/           # Database session
│   │   ├── models/       # SQLAlchemy models
│   │   ├── schemas/      # Pydantic schemas
│   │   ├── services/     # Business logic (AI, risk calculator, report generator)
│   │   └── workers/      # Background tasks
│   ├── alembic/          # Database migrations
│   ├── requirements.txt
│   ├── seed.py           # Demo data seeding script
│   └── .env.example
├── infra/              # Docker configuration
│   ├── docker-compose.yml
│   ├── Dockerfile.backend
│   └── Dockerfile.frontend
├── docs/               # Documentation
└── trustos-plan.md     # Detailed build plan and stages
```

## Quick Start (Docker Compose)

### Prerequisites

- Docker and Docker Compose installed
- Git

### Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd trustos
```

2. Copy environment files:
```bash
cp backend/.env.example backend/.env
```

3. Start all services:
```bash
cd infra
docker-compose up --build
```

4. Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

### Demo Credentials

The seed script creates a demo tenant "Acme Corp" with the following users:

- **Executive (CEO)**: executive@acmecorp.io / TrustOS2024!
- **IT Admin**: it@acmecorp.io / TrustOS2024!
- **TrustOS Admin**: admin@trustos.com / TrustOS-Admin-2024!

## Development Setup (Local)

### Backend Setup

1. Create a Python virtual environment:
```bash
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```

4. Initialize the database:
```bash
python seed.py
```

5. Run the backend server:
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### Frontend Setup

1. Install dependencies:
```bash
cd frontend
npm install
```

2. Set up environment variables:
```bash
cp .env.example .env.local
# Edit .env.local with NEXT_PUBLIC_API_URL=http://localhost:8000
```

3. Run the development server:
```bash
npm run dev
```

## Database Migrations

TrustOS uses Alembic for database migrations. In development, tables are auto-created on startup. For production, use migrations:

```bash
cd backend
alembic revision --autogenerate -m "description"
alembic upgrade head
```

## Key Features

### Phase 1: Vault Audit (Current Implementation)
- Executive dashboard with Cyber Health Score
- Top 3 Risks with AI-translated business impact
- Risk trend visualization (90-day history)
- Findings management with remediation tracking
- Digital footprint center for executive exposure
- Multi-role authentication (Executive, IT Admin, TrustOS Admin)
- Vault Audit Report generation with PDF export

### Phase 2: Monthly Monitoring (Planned)
- Continuous monitoring engine
- Daily automated assessments
- Certificate expiration monitoring
- CVE monitoring
- Cloud posture checks
- Breach intelligence integration

### Phase 3: Full Platform (Planned)
- Attack path visualization
- AI Security Coach
- Executive protection services
- Board reporting
- Advanced integrations

## Configuration

### Backend Environment Variables

See `backend/.env.example` for the full list. Key variables:

- `DATABASE_URL`: PostgreSQL connection string (async)
- `SECRET_KEY`: JWT signing key (generate with `openssl rand -hex 32`)
- `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`: For AI features
- `AI_PROVIDER`: `openai` or `anthropic`

### Frontend Environment Variables

- `NEXT_PUBLIC_API_URL`: Backend API URL

## Security Notes

- All API routes require authentication except `/health` and `/api/v1/auth/login`
- Multi-tenant isolation enforced at the database and API level
- Role-based access control (RBAC) for different user types
- Authorization-first approach: only scan explicitly authorized assets
- Secrets should never be committed to git (use `.env` files, ignored by git)

## Testing

Run backend tests:
```bash
cd backend
pytest
```

Run frontend tests:
```bash
cd frontend
npm test
```

## Deployment

### Production Checklist

- [ ] Change `SECRET_KEY` to a cryptographically secure random value
- [ ] Set strong database passwords
- [ ] Configure production database (Supabase, RDS, etc.)
- [ ] Enable HTTPS/TLS
- [ ] Set up proper CORS origins
- [ ] Configure AI API keys with appropriate rate limits
- [ ] Set up logging and monitoring
- [ ] Enable database backups
- [ ] Review and update security headers
- [ ] Run Alembic migrations instead of auto-create tables

## Documentation

- **Business Plan**: See `readplan.txt` for the complete business strategy
- **Build Plan**: See `trustos-plan.md` for detailed implementation stages
- **API Documentation**: Available at `/docs` when backend is running

## License

Proprietary - All rights reserved

## Support

For technical issues or questions, contact the TrustOS development team.