📁 Project Structure

devdocai/
├── backend/
│   ├── auth/
│   │   ├── jwt.py                  ← JWT create/verify
│   │   ├── github_oauth.py         ← GitHub OAuth flow
│   │   └── routes.py               ← HTTP layer only
│   ├── db/
│   │   ├── database.py             ← async PostgreSQL engine
│   │   └── models.py               ← SQLAlchemy ORM models
│   ├── repositories/
│   │   └── user_repository.py      ← all DB queries isolated here
│   ├── schemas/
│   │   └── auth_schemas.py         ← Pydantic v2 request/response models
│   ├── services/
│   │   └── auth_service.py         ← business logic layer
│   ├── utils/
│   │   ├── helper_auth.py          ← bcrypt password helpers
│   │   └── encryption.py           ← Fernet encryption for tokens
│   ├── mcp/
│   │   └── github_server.py        ← GitHub tools for LangGraph agents
│   ├── agents/
│   │   ├── codebase_parser.py
│   │   ├── doc_generator.py
│   │   ├── brave_researcher.py
│   │   ├── doc_publisher.py
│   │   └── onboarding_chatbot.py
│   ├── graph/
│   │   ├── state.py
│   │   ├── pipeline.py
│   │   └── hitl.py
│   ├── webhooks/
│   │   └── github_pr.py            ← PR merge webhook handler
│   ├── cache/
│   │   └── redis_client.py         ← Upstash Redis caching
│   ├── vectorstore/
│   │   ├── embeddings.py
│   │   └── qdrant_store.py
│   ├── config.py                   ← all env vars, pydantic-settings
│   └── main.py                     ← FastAPI app entry point
├── frontend/                       ← Phase 6
│   ├── app/
│   │   ├── dashboard/
│   │   ├── review/                 ← HITL review panel
│   │   └── chat/                   ← onboarding chatbot UI
└── .github/
    └── workflows/
        └── deploy.yml              ← Phase 7

🏛️ Architecture

Clean layered architecture — every layer has one job:

Route       →  HTTP only (request / response)
    ↓
Service     →  Business logic
    ↓
Repository  →  DB queries only
    ↓
Database

🚀 Getting Started

Prerequisites

• Python 3.12+
• uv — fast Python package manager just like pip
• Docker (for local PostgreSQL)
• A GitHub OAuth App (create one here)

1. Clone the repo

git clone https://github.com/Nevin100/DevDocxAI.git
cd DevDocxAI/backend

2. Install dependencies

uv venv
# Windows
.venv\Scripts\activate
# Mac/Linux
source .venv/bin/activate

uv add -r requirements.txt

3. Setup environment variables

cp .env.example .env
# Fill in your actual values in .env

Generate required keys:

# JWT Secret
python -c "import secrets; print(secrets.token_hex(32))"

# Fernet Encryption Key
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

4. Start local PostgreSQL (Docker)

docker run -d \
  --name devdocai_postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=devdocai \
  -p 5432:5432 \
  -v devdocai_pgdata:/var/lib/postgresql/data \
  postgres:16

5. Run the server

# Windows
.venv\Scripts\python.exe -m uvicorn main:app --reload

# Mac/Linux
uvicorn main:app --reload

6. Open Swagger UI

http://localhost:8000/docs

🔑 Environment Variables

📊 Database Schema

User
 └── Repository
         ├── Document        (DocStatus: PENDING → APPROVED → PUBLISHED)
         └── PipelineRun     (trigger: manual | pr_merge | webhook)

🛣️ Roadmap

📖 Blog Series

Following the build in public on dev.to:

• Part 1 — Foundation: Backend, Auth, DB, GitHub OAuth, MCP
• Part 2 — LangGraph Core + Agents + RAG
• Part 3 — Webhooks + Redis Cache

🤝 Contributing

This project is under active development. Feel free to open issues or PRs.