# douglasymlai/test architecture

> Architecture diagram of the GitHub repository douglasymlai/test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/douglasymlai/test
- Repository: https://github.com/douglasymlai/test

## Overview

##### Project type and purpose
- This is a monorepo full-stack web application (“MCP Hub”) composed of:
- A Python FastAPI backend (REST API + business logic + database migrations + tests)
- A TypeScript/React frontend (Refine + Vite + Shadcn UI + Playwright tests)
- A PostgreSQL database (via Supabase for realtime, auth, storage)
- Docker-Compose orchestration for local development

##### File structure
- Top-level services:
- `/backend` – FastAPI app with `app/api`, `app/core`, `crud.py`, `models.py`, Alembic migrations, scripts & tests
- `/frontend` – React/Refine UI with generated OpenAPI client, components, routes, theme, tests
- `/supabase` – Supabase config for local Postgres + realtime/auth/storage
- `docker-compose.yml` + overrides – orchestrate “backend”, “frontend”, “supabase” profiles
- `/scripts` – CI/CD, build, deploy, client-generation, test helpers
- Key patterns: layered backend (API → core → DB), auto-generated client SDK, containerized services

##### README for additional insights
- Tech stack confirms FastAPI + SQLModel + Pydantic + PostgreSQL + Supabase
- Frontend uses Refine + Vite + React + Shadcn UI + Playwright
- Auth: StackAuth + Supabase
- Local dev: Docker Compose profiles for backend, frontend, Supabase

a. Main components
- Browser (User’s UI)
- Frontend Container (React/Refine app)
- API Gateway / Backend Container (FastAPI app)
- PostgreSQL Database (hosted by Supabase)
- Supabase Real-time & Auth service
- External Auth provider (StackAuth, if separate)
- CI/CD & Deployment (Dokploy) – optional, for end-to-end flow

b. Relationships & interactions
1. User ↔ Browser – interacts with frontend UI
2. Browser → Frontend – HTTP(S) requests; fetch UI assets via Nginx or Vite dev server
3. Frontend → Backend API – REST calls (CRUD, auth) using generated OpenAPI client
4. Backend → Database – SQLModel ORM queries to PostgreSQL
5. Backend ↔ Supabase – realtime subscriptions, file storage, auth management
6. Backend → External Auth (StackAuth) – user login/registration flows
7. CI/CD pipelines → Deployment – Docker images → Dokploy

c. Architectural patterns & design principles
- Layered backend:
– API layer (`app/api/routes`)
– Core services (`app/core`, `crud.py`, `models.py`)
– Data layer (PostgreSQL + Alembic migrations)
- Client SDK generation: openapi-ts to keep frontend types in sync
- Containerization: each service in its own Dockerfile + Docker Compose profiles
- Supabase for offloading realtime and auth/storage concerns

d. Technologies & frameworks
- FastAPI, SQLModel, Pydantic, Alembic (backend)
- React + Refine + Vite + TypeScript + Shadcn UI (frontend)
- PostgreSQL, Supabase (DB & realtime + auth + storage)
- Docker Compose, Dockerfiles (orchestration & containers)
- Playwright, Pytest (testing)
- Dokploy (deployment)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser"]:::ui
        FrontendContainer["Frontend Container (React/Refine App) (port 3000)"]:::ui
        Browser <--->|"interacts"| FrontendContainer
    end

    %% Frontend Container Components
    subgraph "Frontend Container"
        OpenAPI["OpenAPI Client SDK"]:::ui
        Components["UI Components"]:::ui
        RoutesUI["Routes & Layouts"]:::ui
        Theme["Theme & UI Utilities"]:::ui
        TestsFE["Playwright Tests"]:::ui

        OpenAPI --> Components
        Components --> RoutesUI
        RoutesUI --> Theme
        FrontendContainer --> OpenAPI
        FrontendContainer --> Components
        FrontendContainer --> RoutesUI
        FrontendContainer --> Theme
        FrontendContainer --> TestsFE
    end

    %% Application Layer
    subgraph "Application Layer"
        BackendContainer["Backend Container (FastAPI App) (port 8000)"]:::backend

        subgraph "API Layer"
            APIRoutes["API Routes"]:::backend
            APIDeps["API Deps & Main"]:::backend
        end

        subgraph "Core Services"
            CoreServices["Core Services & Config"]:::backend
            ModelsCRUD["Models & CRUD Logic"]:::backend
        end

        Migrations["Alembic Migrations"]:::backend
        EmailTemplates["Email Templates Service"]:::backend
        StartupScripts["Backend Startup Scripts"]:::backend
        TestsBE["Pytest Tests"]:::backend

        BackendContainer --> APIRoutes
        BackendContainer --> APIDeps
        BackendContainer --> CoreServices
        BackendContainer --> ModelsCRUD
        BackendContainer --> Migrations
        BackendContainer --> EmailTemplates
        BackendContainer --> StartupScripts
        BackendContainer --> TestsBE
    end

    %% Data Layer and External Services
    subgraph "Data Layer"
        Postgres["PostgreSQL Database (5432)"]:::datadb
    end

    subgraph "Supabase Services"
        Supabase["Supabase (Realtime, Auth, Storage)"]:::datadb
    end

    StackAuth["External Auth Provider (StackAuth)"]:::external
    DockerCompose["Docker Compose Orchestration"]:::external
    CICDScripts["CI/CD & Deployment Scripts"]:::external

    %% Interactions
    FrontendContainer -->|"REST calls"| BackendContainer
    BackendContainer -->|"ORMqueries"| Postgres
    BackendContainer -->|"realtime/auth/storage"| Supabase
    BackendContainer -->|"authflows"| StackAuth

    DockerCompose --> FrontendContainer
    DockerCompose --> BackendContainer
    DockerCompose --> Supabase

    CICDScripts -->|"build&deploy"| DockerCompose
    CICDScripts -->|"generateClient"| OpenAPI
    CICDScripts -->|"runTests"| TestsFE
    CICDScripts -->|"runTests"| TestsBE

    %% Click Events
    click OpenAPI "https://github.com/douglasymlai/test/tree/main/frontend/src/client/"
    click Components "https://github.com/douglasymlai/test/tree/main/frontend/src/components/"
    click RoutesUI "https://github.com/douglasymlai/test/tree/main/frontend/src/routes/"
    click Theme "https://github.com/douglasymlai/test/blob/main/frontend/src/theme.tsx"
    click Theme "https://github.com/douglasymlai/test/tree/main/frontend/src/components/ui/"
    click TestsFE "https://github.com/douglasymlai/test/tree/main/frontend/tests/"
    click BackendContainer "https://github.com/douglasymlai/test/tree/main/backend/"
    click APIRoutes "https://github.com/douglasymlai/test/tree/main/backend/app/api/routes/"
    click APIDeps "https://github.com/douglasymlai/test/blob/main/backend/app/api/deps.py"
    click APIDeps "https://github.com/douglasymlai/test/blob/main/backend/app/api/main.py"
    click CoreServices "https://github.com/douglasymlai/test/tree/main/backend/app/core/"
    click ModelsCRUD "https://github.com/douglasymlai/test/blob/main/backend/app/models.py"
    click ModelsCRUD "https://github.com/douglasymlai/test/blob/main/backend/app/crud.py"
    click Migrations "https://github.com/douglasymlai/test/tree/main/backend/app/alembic/"
    click Migrations "https://github.com/douglasymlai/test/blob/main/backend/alembic.ini"
    click EmailTemplates "https://github.com/douglasymlai/test/tree/main/backend/app/email-templates/"
    click StartupScripts "https://github.com/douglasymlai/test/blob/main/backend/app/backend_pre_start.py"
    click StartupScripts "https://github.com/douglasymlai/test/blob/main/backend/scripts/prestart.sh"
    click TestsBE "https://github.com/douglasymlai/test/tree/main/backend/app/tests/"
    click Supabase "https://github.com/douglasymlai/test/blob/main/supabase/config.toml"
    click DockerCompose "https://github.com/douglasymlai/test/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/douglasymlai/test/blob/main/docker-compose.override.yml"
    click CICDScripts "https://github.com/douglasymlai/test/tree/main/scripts/"

    %% Styling
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datadb fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
