AI Team OS

Hire an AI team. Ship real work.

AI Team OS is a production-ready SaaS workspace where users create AI employees — Software Engineer, Designer, QA, Product Manager, Researcher, Marketing Manager, Content Writer — that collaborate on projects through chat, kanban, files, and RAG-grounded answers.

AI Team OS gives product teams a multi-agent operating system:

• Create workspaces and projects
• Assign tasks on a drag-and-drop kanban board
• Chat with specialized AI employees (solo or orchestrated)
• Upload documents for Retrieval-Augmented Generation (RAG)
• Import GitHub documentation into the knowledge base
• Track analytics, notifications, roles, and billing-ready plans

The monorepo is portfolio-quality and deployment-ready: FastAPI + PostgreSQL/pgvector backend, Next.js 15 frontend, Docker Compose, CI, OpenAPI docs, and tests.

┌──────────────────┐          ┌─────────────────────┐
│  Next.js 15 App  │  HTTPS   │  FastAPI (Python)   │
│  Vercel / Docker │ ───────► │  Railway / Docker   │
└──────────────────┘          └──────────┬──────────┘
                                         │
              ┌──────────────────────────┼──────────────────────────┐
              ▼                          ▼                          ▼
       ┌─────────────┐          ┌────────────────┐          ┌──────────────┐
       │ PostgreSQL  │          │ OpenAI         │          │ Supabase     │
       │ + pgvector  │          │ Responses API  │          │ Auth/Storage │
       └─────────────┘          │ + Embeddings   │          └──────────────┘
                                └────────────────┘

See docs/architecture/overview.md for layering, auth, and orchestration details.

Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS v4, shadcn-style Radix UI, React Query, Zustand, Framer Motion, dnd-kit, Recharts, next-themes, Supabase JS

Backend: FastAPI, Pydantic v2, SQLAlchemy 2 (async), Alembic, structlog, OpenAI SDK, pgvector, pypdf / python-docx

Data & infra: PostgreSQL 16 + pgvector, Redis, Docker Compose, GitHub Actions CI

Deploy targets: Vercel (frontend) · Railway (backend) · Supabase (auth/storage)

.
├── frontend/                 # Next.js 15 application
│   └── src/
│       ├── app/              # App Router pages
│       ├── components/       # UI + layout
│       ├── lib/              # API client, demo data, supabase
│       ├── stores/           # Zustand auth store
│       └── types/
├── backend/                  # FastAPI application
│   ├── app/
│   │   ├── api/v1/           # REST routes + OpenAPI
│   │   ├── agents/           # Catalog + orchestration runtime
│   │   ├── core/             # Config, security, deps
│   │   ├── domain/           # Enums + Pydantic schemas
│   │   ├── infrastructure/   # DB, repos, storage, GitHub
│   │   ├── rag/              # Parse, chunk, embed, retrieve
│   │   └── services/         # Application use-cases
│   ├── alembic/              # Migrations (pgvector)
│   └── tests/
├── docker-compose.yml        # One-command full stack
├── docker/                   # Dockerfiles
├── docs/                     # Architecture + screenshots
├── scripts/                  # Dev helpers + screenshot capture
└── .github/workflows/        # CI

Captured from the running app in demo mode. Replace anytime with node scripts/capture-screenshots.cjs.

git clone <your-repo-url> ai-team-os
cd ai-team-os
cp .env.example .env   # optional — compose has safe defaults
docker compose up --build

That starts Postgres + pgvector, Redis, the FastAPI backend, and the Next.js frontend.

Open /login → Continue with demo workspace (or sign up against the API).

Equivalent helper:

chmod +x scripts/docker-up.sh
./scripts/docker-up.sh

Stop everything:

docker compose down

• Node.js 22+
• Python 3.12+
• Docker (for Postgres + pgvector at minimum)

git clone <your-repo-url> ai-team-os
cd ai-team-os
cp .env.example .env

docker compose up -d db redis

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

API docs: http://localhost:8000/docs

cd frontend
npm ci
npm run dev

App: http://localhost:3000

Demo mode: open /login → Continue with demo workspace (works without the API).

See .env.example. Important keys:

Single command (recommended):

docker compose up --build

Optional env file (API keys, secrets):

cp .env.example .env

Services:

Production-style frontend image: docker/frontend.Dockerfile (standalone Next.js).

1. docker compose up -d db
2. Backend: uvicorn app.main:app --reload (from backend/ with venv)
3. Frontend: npm run dev (from frontend/)
4. Visit /login or use Continue with demo workspace

Without OpenAI keys, agents respond with structured offline stubs; embeddings use deterministic local vectors so RAG still runs end-to-end.

1. Import the frontend/ directory as a Vercel project
2. Set NEXT_PUBLIC_API_URL to your Railway API URL
3. Set Supabase public keys if using OAuth
4. Deploy

1. Create a Railway service from backend/ (or Docker via docker/backend.Dockerfile)
2. Attach Postgres (enable vector extension) or use the pgvector/pgvector image
3. Set env vars from .env.example
4. Run alembic upgrade head on release
5. Start: uvicorn app.main:app --host 0.0.0.0 --port $PORT

• Enable Email + OAuth providers
• Create storage bucket project-files
• Copy URL, anon key, service role, JWT secret into .env

Interactive OpenAPI UI:

• Swagger: /docs
• ReDoc: /redoc
• Schema: /openapi.json

Primary route groups under /api/v1:

• /auth · /users · /workspaces · /projects · /tasks
• /agents · /chat · /documents · /notifications
• /analytics · /search · /billing · /github

# Backend unit tests
cd backend && source .venv/bin/activate
PYTHONPATH=. pytest tests/unit -q

# Frontend
cd frontend
npm run lint
npm run typecheck
npm run build

Integration tests: set RUN_INTEGRATION_TESTS=1 with a live database.

CI runs on every push/PR via .github/workflows/ci.yml.

• Streaming SSE for agent replies
• Real-time presence (Redis / WebSockets)
• Agent tool execution sandbox
• Workspace invites + email notifications
• Stripe Customer Portal
• Evaluation harness for RAG quality
• Mobile native shell (Expo)

See docs/CONTRIBUTING.md.

1. Fork → feature branch
2. Keep PRs focused; add tests
3. Run lint + unit tests
4. Open a PR with a clear description

MIT License — see LICENSE.

• Stronger PydanticAI / Agents SDK tool graphs
• Hybrid search (BM25 + vectors)
• Per-agent evaluation dashboards
• SOC2-oriented audit logging
• Multi-region deployments

Built as an open-source, enterprise-quality reference for collaborative AI employee workspaces.