Backend Architecture

app/
├── main.py                       # FastAPI app entry, lifespan, CORS, middleware
├── core/
│   ├── config.py                 # Pydantic settings (all env vars)
│   ├── database.py               # Async SQLAlchemy engine + session
│   ├── neo4j_client.py           # Neo4j async driver singleton
│   └── neo4j_schema.py           # Constraints + indexes
├── models/
│   ├── user.py                   # GitHub users
│   ├── installation.py           # Connected repos + webhook secrets
│   ├── event.py                  # Incoming webhook events
│   ├── workflow.py               # PR review workflow runs
│   └── oauth_state.py            # CSRF state tokens
├── api/v1/
│   ├── webhooks.py               # GitHub webhook receiver
│   ├── repos.py                  # Connect / disconnect / rescan
│   ├── reviews.py                # PR review history
│   ├── events.py                 # Event queries
│   ├── analytics.py              # Team metrics
│   └── memory.py                 # Mem0 CRUD + project map
├── auth/
│   ├── router.py                 # GitHub OAuth flow
│   ├── dependencies.py           # get_current_user() dependency
│   ├── jwt_utils.py              # JWT sign + verify
│   └── token_encryption.py       # Fernet encrypt/decrypt GitHub tokens
├── services/
│   ├── pr_review_service.py      # PR review orchestrator
│   ├── ai_service.py             # Claude integration + parallel agents
│   ├── context_service.py        # Mem0 + Neo4j + MCP context builder
│   ├── graph_builder.py          # Neo4j read + write operations
│   ├── memory_adapter.py         # Mem0 async wrapper
│   ├── memory_extractor.py       # Post-review memory extraction
│   └── project_scanner.py        # Initial repo scan on connect
├── integrations/github/
│   ├── client.py                 # GitHub REST API (diff, files, post review)
│   └── webhook_manager.py        # Install / remove webhooks
└── mcp/
    ├── server.py                 # FastMCP server (4 tools + 1 resource)
    └── client.py                 # MCP client (Linear, Sentry, Slack)

# app/main.py:88
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    await asyncio.to_thread(_run_migrations)  # Alembic
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    await init_driver()  # Neo4j
    await create_schema()  # Neo4j constraints
    asyncio.create_task(_scan_unindexed_repos())  # Background backfill
    
    yield
    
    # Shutdown
    await engine.dispose()
    await close_driver()

# app/main.py:143
ALLOWED_ORIGINS = [
    "http://localhost:5173",
    "http://localhost:3000",
    "http://localhost:3001",
    settings.FRONTEND_URL,
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,  # Required for JWT cookies
    allow_methods=["GET", "POST", "DELETE", "PATCH", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization"],
)

# app/main.py:180
@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    duration = round((time.time() - start) * 1000, 2)
    logger.info(f"{request.method} {request.url.path} → {response.status_code} ({duration}ms)")
    return response

# app/main.py:164
try:
    from app.mcp.server import mcp as _mcp_server
    app.mount("/mcp", _mcp_server.sse_app())
    logger.info("Nectr MCP server mounted at /mcp")
except Exception as _mcp_err:
    logger.warning("MCP server not mounted: %s", _mcp_err)

# app/main.py:190
@app.get("/health")
async def health_check():
    uptime_seconds = round(time.time() - startup_time, 1)
    
    # Check PostgreSQL
    db_status = "healthy"
    try:
        async with async_session() as session:
            await session.execute(text("SELECT 1"))
    except Exception as e:
        db_status = f"unhealthy: {str(e)}"
    
    # Check Neo4j
    neo4j_status = "not configured"
    if neo4j_available():
        try:
            async with get_session() as session:
                await session.run("RETURN 1")
            neo4j_status = "healthy"
        except Exception as e:
            neo4j_status = f"unhealthy: {str(e)}"
    
    return {
        "status": "healthy",
        "service": settings.APP_NAME,
        "version": settings.APP_VERSION,
        "environment": settings.APP_ENV,
        "uptime_seconds": uptime_seconds,
        "database": db_status,
        "neo4j": neo4j_status,
    }

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # App
    APP_NAME: str = "Nectr"
    APP_VERSION: str = "1.0.0"
    APP_ENV: str = "development"
    DEBUG: bool = False
    LOG_LEVEL: str = "INFO"
    
    # URLs
    BACKEND_URL: str
    FRONTEND_URL: str
    
    # Database
    DATABASE_URL: str
    
    # Neo4j
    NEO4J_URI: str
    NEO4J_USERNAME: str
    NEO4J_PASSWORD: str
    
    # Auth
    SECRET_KEY: str  # For JWT + Fernet
    GITHUB_CLIENT_ID: str
    GITHUB_CLIENT_SECRET: str
    GITHUB_PAT: str  # Personal access token for posting reviews
    
    # AI
    ANTHROPIC_API_KEY: str
    ANTHROPIC_MODEL: str = "claude-sonnet-4-20250514"
    
    # Mem0
    MEM0_API_KEY: str
    
    # MCP (optional)
    LINEAR_MCP_URL: str | None = None
    LINEAR_API_KEY: str | None = None
    SENTRY_MCP_URL: str | None = None
    SENTRY_AUTH_TOKEN: str | None = None
    SLACK_MCP_URL: str | None = None
    
    # Feature flags
    PARALLEL_REVIEW_AGENTS: bool = False
    
    class Config:
        env_file = ".env"