# TrustOS

The AI Operating System for Cyber Resilience

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.

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