Skip to content
3 min read · 616 words

Project Structure

A guided tour of the repository: two deployable projects (backend, frontend), the documentation site, and two learning sandboxes.

Top level

veyraops_ai/
├── backend/              # FastAPI service (deployable)
├── frontend/             # Next.js 15 app (deployable)
├── docs/                 # This documentation (MkDocs Material)
├── mkdocs.yml            # Docs site configuration
├── requirements.txt      # Docs build dependencies (pip)
├── pyproject.toml        # Docs build dependencies (uv) — root project is the docs site
├── vercel.json           # Vercel build config for the docs site
├── learn_backend/        # Learning sandbox — NOT part of the product
├── learn_frontend/       # Learning sandbox — NOT part of the product
├── CLAUDE.md             # Instructions for AI coding assistants
├── DEPLOYMENT.md         # Vercel deployment guide for the docs
└── README.md             # Repository readme

The root pyproject.toml builds the documentation site (MkDocs). The backend backend/pyproject.toml is the product API. Run uv sync in each directory for its own purpose.

Backend — backend/

backend/
├── pyproject.toml            # Python ≥3.14; fastapi, sqlalchemy, openai, chromadb, langgraph…
├── uv.lock                   # Locked dependency versions
├── README.md                 # Architecture and data-flow diagrams
└── app/
    ├── main.py               # FastAPI entry point → docs: Application Entry
    ├── database.py           # Engine, sessions, startup migrations → Database Layer
    ├── models.py             # 9 SQLAlchemy models → ORM Models
    ├── schemas.py            # Pydantic request/response schemas → Schemas
    ├── routers/
    │   ├── agents.py         # /agents endpoints: CRUD, chat, email, tasks, workflows, dashboard
    │   └── documents.py      # /agents/{id}/documents: upload, search, RAG ask
    ├── services/
    │   ├── openai_service.py             # Chat, email analysis, RAG answer, retrieval evaluator
    │   ├── multi_agent_email_service.py  # Analysis / Reply / Reviewer agents
    │   ├── rag_graph_service.py          # LangGraph corrective RAG graph
    │   ├── document_service.py           # Chunking, embeddings, Chroma store/search
    │   └── monitoring_service.py         # Token & cost estimation
    ├── agentops.db           # SQLite database (created at runtime, gitignored)
    └── chroma_db/            # Chroma vector store (created at runtime, gitignored)

Each module has a dedicated documentation page — start at Backend Overview.

backend/app/delete.py, exercise_delete.py, practice_solution.py, solution_delete.py, and backend/test_delete.py are practice scripts left over from learning exercises. They are not imported by main.py and are not part of the application. The real code is only what main.py imports.

Frontend — frontend/

frontend/
├── package.json              # next 15, react 19, tailwindcss, typescript
├── DESIGN.md                 # Design tokens: colors, typography, spacing → Design System
├── app/
│   ├── layout.tsx            # Root layout: fonts (Inter, JetBrains Mono, Material Symbols)
│   ├── page.tsx              # / → redirects to /dashboard
│   ├── globals.css           # Tailwind entry + global styles
│   ├── dashboard/
│   │   ├── page.tsx          # Server component: fetches /agents/1/dashboard
│   │   ├── loading.tsx       # Route loading state
│   │   └── error.tsx         # Route error boundary
│   ├── agents/
│   │   ├── page.tsx          # Server component: fetches /agents/
│   │   └── loading.tsx
│   ├── create-agent/
│   │   └── page.tsx          # Renders the CreateAgentForm client component
│   └── api/
│       └── agents/route.ts   # POST proxy → backend /agents/ → API Proxy pattern
├── components/
│   ├── layout/               # Sidebar, Topbar
│   ├── dashboard/            # StatCard, PerformanceCard, RecentActivity
│   ├── agents/               # AgentCard
│   └── create-agent/         # CreateAgentForm (client component)
└── *.html                    # Loose HTML files at the root are design mockups, not served by Next

Full walkthrough: Frontend Overview.

Documentation — docs/ and friends

docs/                 # Markdown sources (this site)
mkdocs.yml            # Theme, plugins, navigation
requirements.txt      # mkdocs, mkdocs-material, plugins (for pip-based builds)
pyproject.toml        # Same deps for uv-based builds (Vercel uses `uv run mkdocs build`)
vercel.json           # buildCommand + outputDirectory: site/
site/                 # Build output (gitignored, regenerated)

See Docs Deployment.

Learning sandboxes

learn_backend/ and learn_frontend/ contain course/learning material. They are excluded from deployment (.vercelignore) and are never imported by the product code. Ignore them when reasoning about the system.

Naming: VeyraOps vs AgentOps

The repository and documentation are branded VeyraOps AI; the code base predates the rename and still uses AgentOps AI internally — the FastAPI title, the frontend UI header, the database file agentops.db, and the env-var prefix AGENTOPS_*. They are the same product. See the Glossary.

PreviousConfigurationNextArchitecture