How projecttech4devai/ai-platform works
Project type and purpose
• This is a monolithic backend service built with FastAPI (Python) that provides a RESTful API for an AI Platform.
• It handles user management, organizations, projects, API keys, document/collection storage, AI conversations (via OpenAI), email notifications, and benchmarking CLI commands.
• It uses Docker Compose for local development and deployment, Alembic for database migrations, and Postgres as its primary data store.
File structure
• Top level: configuration files (.env.example, docker-compose.yml, CI/CD workflows, scripts), project‐wide docs, deployment and development guides.
• backend/: the entire application lives here.
• app/main.py launches the FastAPI app.
• app/api/: defines routes, dependencies, and autogenerated markdown docs per endpoint.
• app/crud/: data access layer interacting with SQLAlchemy models.
• app/models/: ORM models representing database tables.
• app/core/: configuration, security, middleware, logging, cloud storage abstraction, OpenAI provider, Langfuse integration.
• app/email-templates/: MJML templates compiled to HTML for outbound emails.
• app/cli/: command-line benchmarking tools.
• alembic/: migration scripts and environment for schema evolution.
• scripts/ & backend/scripts/: convenience shell scripts for linting, testing, prestart, deployments.
• Docker: backend/Dockerfile, .dockerignore.
• Deployment: docker-compose.yml (+ overrides), deployment.md, CD workflows in .github/workflows.
README for additional insights
• Confirms use of Docker Compose for “watch” mode and Uvicorn, Postgres, environment‐driven configuration, and template origin (full‐stack FastAPI template).
• Points to separate backend README and deployment/development guides.
• No bundled frontend—focus is purely the API and CLI.
Main components
a. FastAPI Application
• Routers (app/api/routes)
• Dependency injection (app/api/deps)
• Middleware, exception handlers, security (app/core)
b. Data Layer
• SQLAlchemy ORM models (app/models)
• Alembic migrations (backend/alembic)
• Postgres database
c. Core & Utilities
• Configuration, logging, util functions (app/core)
• Cloud storage abstraction (e.g., S3)
• Email template compiler & SMTP or transactional email service
• External AI provider (OpenAI, via app/core/providers.py)
• Langfuse telemetry integration
d. CLI Benchmarking Tool
• Entrypoint (app/cli/main.py)
• Commands and test datasets (app/cli/bench)
e. External Services
• OpenAI API
• Email/SMTP provider
• Object storage (via cloud/storage.py)
• Langfuse analytics endpoint
f. DevOps & CI/CD
• Docker Compose services (FastAPI, Postgres, Traefik)
• GitHub Actions workflows
• Build and deployment scripts
Relationships and interactions
• User/client → FastAPI (HTTP REST calls)
• FastAPI → Postgres (ORM CRUD operations)
• FastAPI → Alembic (at startup or CI for migrations)
• FastAPI → Cloud storage (upload/download documents)
• FastAPI → OpenAI API (chat, embeddings)
• FastAPI → Langfuse (logging telemetry)
• FastAPI → Email service (send password resets, account invites)
• CLI tool → FastAPI or DB directly (depending on the command)
• Docker Compose orchestrates FastAPI, Postgres, reverse proxy (Traefik)
Architectural patterns & principles
• Layered architecture: API → service/deps → CRUD → models → database
• Clear separation of concerns: core/config, API routes, data access, utilities, CLI
• Migrations decoupled via Alembic
• Environment‐driven configuration for 12-factor compliance
• Containerized services for consistency across environments