# el-ouardy/atlaslingua architecture

> Architecture diagram of the GitHub repository el-ouardy/atlaslingua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/el-ouardy/atlaslingua
- Repository: https://github.com/el-ouardy/atlaslingua

## Overview

##### Main Components
- Frontend Web Client
– React + TypeScript application (src/)
– UI library: TailwindCSS / Shadcn/ui
– Bundler/dev server: Vite (vite.config.ts)
- Backend API
– Flask application (api/app/)
– REST endpoints organized by feature (routes/*.py)
– Business logic in services/
– Data validation in schemas/
- Datastores
– Relational DB: MySQL (SQLAlchemy models + Alembic migrations)
– Firestore (Firebase) for community forum data
- Serverless Functions
– Firebase Functions (functions/src/index.ts) enforcing Firestore rules
- Third-Party Services
– Algolia search indexing
– SendGrid (email_service.py)
– (Implicit) LLM provider in language_model.py (e.g. OpenAI)
- Hosting & Deployment
– Frontend: Vercel / Netlify / Firebase Hosting
– Backend: Heroku (Procfile) or any container orchestration
– Firebase: managed by firebase.json / .firebaserc

##### Relationships & Data Flows
- User → Browser → React App
- React App → HTTP(S) → Flask REST API (CRUD on users, history, favorites, contributions, translation/summarization requests)
- Flask API → MySQL (SQLAlchemy) for persistent records (users, dictionaries, history, feedback, etc.)
- Flask API ↔ Firebase Admin SDK (firebase_service.py) for community forum data (posts, comments)
- React App → Firebase SDK → Firestore (community forum UI)
- React App → Algolia API for search queries (dictionary/community)
- Flask API → SendGrid API for transactional emails (password reset, notifications)
- Flask API → LLM Provider (language_model.py) for translation & summarization

##### Architectural Patterns
- Layered architecture in Backend
– Routing layer (routes/)
– Service layer (services/)
– Data layer (models/, schemas/)
– Utility layer (utils/)
- Separation of concerns in Frontend
– UI components (components/)
– State management (contexts/)
– API clients (services/api.ts)
– Domain models (models/)
- Micro-service-like split between Flask API and Firebase Functions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Web Client" 
        direction TB
        ReactApp["React App<br/>Vite, Tailwind, Shadcn/ui"]:::frontend
        SRC["src"]:::frontend
        VITE["vite.config.ts"]:::frontend
        UI["UI Components"]:::frontend
        MAIN["main.tsx"]:::frontend
        STYLE1["tailwind.config.js"]:::frontend
        POSTCSS["postcss.config.js"]:::frontend
        INDEXCSS["index.css"]:::frontend
        CTX["Context Providers"]:::frontend
        API_CLIENT["API Client"]:::frontend
        MODELS["Domain Models"]:::frontend
    end

    %% Backend Layer
    subgraph "Flask API" 
        direction TB
        RUN["run.py"]:::backend
        CONFIG["config.py"]:::backend
        PROCFILE["Procfile"]:::backend
        ROUTES["Routes"]:::backend
        SERVICES["Services"]:::backend
        SCHEMAS["Schemas"]:::backend
        MODELS_API["Models"]:::backend
        MIGRATIONS["Migrations"]:::backend
        FIREBASE_ADMIN["Firebase Admin SDK"]:::backend
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        MySQLDB["MySQL Database"]:::datastore
        Firestore["Firestore"]:::datastore
    end

    %% Serverless Functions
    subgraph "Firebase Functions"
        direction TB
        FUNC_INDEX["index.ts"]:::serverless
        FUNC_PKG["package.json"]:::serverless
        FUNC_TS["tsconfig.json"]:::serverless
        RULES["Firestore Rules"]:::serverless
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Algolia["Algolia"]:::external
        SendGrid["SendGrid"]:::external
        LLM["LLM Provider"]:::external
    end

    %% Hosting & Deployment
    subgraph "Hosting & Deployment"
        direction TB
        FIREBASE_CONFIG["firebase.json/.firebaserc"]:::hosting
        VERCEL["vercel.json"]:::hosting
    end

    %% Connections
    ReactApp -->|"HTTP(S)"| RUN
    ReactApp -->|"SDK"| Firestore
    ReactApp -->|"API"| Algolia
    RUN -->|"ORM"| MySQLDB
    RUN -->|"Admin SDK"| Firestore
    RUN -->|"Send Email"| SendGrid
    RUN -->|"LLM Call"| LLM
    FUNC_INDEX -->|"Deploy Rules"| Firestore

    %% Click Events
    click SRC "https://github.com/el-ouardy/atlaslingua/tree/main//src"
    click VITE "https://github.com/el-ouardy/atlaslingua/blob/main/vite.config.ts"
    click UI "https://github.com/el-ouardy/atlaslingua/tree/main//src/components/ui"
    click MAIN "https://github.com/el-ouardy/atlaslingua/blob/main//src/main.tsx"
    click STYLE1 "https://github.com/el-ouardy/atlaslingua/blob/main/tailwind.config.js"
    click POSTCSS "https://github.com/el-ouardy/atlaslingua/blob/main/postcss.config.js"
    click INDEXCSS "https://github.com/el-ouardy/atlaslingua/blob/main//src/index.css"
    click CTX "https://github.com/el-ouardy/atlaslingua/tree/main//src/contexts"
    click API_CLIENT "https://github.com/el-ouardy/atlaslingua/blob/main//src/services/api.ts"
    click MODELS "https://github.com/el-ouardy/atlaslingua/tree/main//src/models"
    click RUN "https://github.com/el-ouardy/atlaslingua/blob/main//api/run.py"
    click CONFIG "https://github.com/el-ouardy/atlaslingua/blob/main//api/config.py"
    click PROCFILE "https://github.com/el-ouardy/atlaslingua/tree/main//api/Procfile"
    click ROUTES "https://github.com/el-ouardy/atlaslingua/tree/main//api/app/routes"
    click SERVICES "https://github.com/el-ouardy/atlaslingua/tree/main//api/app/services"
    click SCHEMAS "https://github.com/el-ouardy/atlaslingua/tree/main//api/app/schemas"
    click MODELS_API "https://github.com/el-ouardy/atlaslingua/tree/main//api/app/models"
    click MIGRATIONS "https://github.com/el-ouardy/atlaslingua/tree/main//api/migrations"
    click FIREBASE_ADMIN "https://github.com/el-ouardy/atlaslingua/tree/main//api/app/firebase"
    click FUNC_INDEX "https://github.com/el-ouardy/atlaslingua/blob/main//functions/src/index.ts"
    click FUNC_PKG "https://github.com/el-ouardy/atlaslingua/blob/main//functions/package.json"
    click FUNC_TS "https://github.com/el-ouardy/atlaslingua/blob/main//functions/tsconfig.json"
    click RULES "https://github.com/el-ouardy/atlaslingua/blob/main//functions/firestore/firestore.rules"
    click FIREBASE_CONFIG "https://github.com/el-ouardy/atlaslingua/blob/main/firebase.json"
    click VERCEL "https://github.com/el-ouardy/atlaslingua/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#e3fcec,stroke:#2d6a4f,color:#2d6a4f;
    classDef backend fill:#e0f7ff,stroke:#0277bd,color:#0277bd;
    classDef datastore fill:#fff3e0,stroke:#ef6c00,color:#ef6c00,stroke-dasharray: 5 5;
    classDef serverless fill:#f3e5f5,stroke:#8e24aa,color:#8e24aa;
    classDef external fill:#fce4ec,stroke:#d81b60,color:#d81b60,stroke-dasharray: 2 2;
    classDef hosting fill:#e8eaf6,stroke:#3949ab,color:#3949ab;
```
