# jjoenasr/fastapi-ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/jjoenasr/fastapi-ecommerce
- Repository: https://github.com/jjoenasr/fastapi-ecommerce

## Overview

##### Project Type and Purpose
- This is a backend‐only, full‑stack API service for an e‑commerce platform, implemented twice: one version uses a relational database (SQLite via SQLModel), the other uses MongoDB (Beanie ODM).
- Core capabilities: user auth, product CRUD, order processing, stock management, search & pagination, image uploads, and an AI‑powered RAG chatbot.

##### File Structure
- Two sibling directories:
- ecommerce‑rdb/ – SQLModel + SQLite version
- ecommerce‑mongodb/ – Beanie + MongoDB version
- Common files in each implementation:
- main.py – FastAPI app bootstrap
- database.py – DB connection & session/engine setup
- models.py – ORM/ODM models (User, Product, Order, etc.)
- routes/ (auth.py, store.py, chat.py) – API endpoint definitions
- utils.py – common helpers (JWT creation, hashing, pagination)
- seed.py – optional data seeder using models & datasets/faq.csv
- requirements.txt – dependency list
- datasets/faq.csv – seed data for the RAG chatbot.

##### Extract Insights from README
- Two interchangeable backends sharing identical route contracts.
- Security: bcrypt password hashing, JWT tokens, OAuth2 dependencies, CORS middleware.
- External dependency: Google Gemini API (via `GOOGLE_API_KEY`) to power the RAG chatbot.

##### Main Components
a. External Clients
- Web/Mobile clients or API tools hitting the HTTP interface (port 8000).
b. API Gateway / FastAPI Layer
- Entry point: main.py → includes routers: auth, store, chat.
c. Route Controllers
- AuthController, StoreController, ChatController – HTTP-to-service translation.
d. Service / Business Logic Layer (optionally show as part of controllers or separate)
- JWT management, order processing workflows, pagination & filtering logic.
e. Data Access Layer
- Relational version: SQLModel sessions, SQLite engine.
- Document version: Beanie ODM, MongoClient connection.
f. Databases
- SQLite (ecommerce‑rdb)
- MongoDB (ecommerce‑mongodb)
g. External Services
- Google Gemini API for AI‑RAG chatbot.
h. Supporting Modules
- Utils (hashing, token utils, common exceptions)
- Seed Script & FAQ dataset (initial data import)
i. Infrastructure / DevOps (optional)
- Environment variables: SECRET_KEY, ACCESS_TOKEN_EXPIRE_MINUTES, MONGO_URI
- Uvicorn server, Docker (if used), CI/CD pipelines.

##### Relationships & Data Flows
- Client → FastAPI (HTTP request)
- FastAPI router → service logic → data access layer → Database
- Chat route → RAG service → External Gemini API → returns answer to client
- Seed script → reads CSV → models → inserts into DB
- Utils module injected via dependencies (e.g., `Depends(get_db)`).

##### Architectural Patterns & Design Principles
- Layered Architecture: Presentation (routes) → Business Logic → Data Access
- Dependency Injection: FastAPI `Depends` for DB sessions and auth
- Single Responsibility: each route file handles one domain (auth, store, chat)
- Asynchronous IO in MongoDB version (Beanie + async routes) versus sync in SQLite version
- Environment‑driven configuration for flexibility.

##### Technologies & Frameworks
- FastAPI, Uvicorn
- SQLModel (rdb) / Beanie (mongodb)
- SQLite / MongoDB
- Python 3.8+
- bcrypt, PyJWT, OAuth2 (security)
- Pandas or CSV reader in seed.py
- Google Gemini API client

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Clients
    subgraph "Layer 1: Clients"
        Client["Web/Mobile Clients/API Tools"]:::client
    end

    %% Layer 2: API Gateway & Routers
    subgraph "Layer 2: API Gateway & Routers"
        APIRDB["FastAPI App\n(Relational)"]:::api
        APIMongo["FastAPI App\n(Document)"]:::api
    end

    Client -->|HTTP Request| APIRDB
    Client -->|HTTP Request| APIMongo

    click APIRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/main.py"
    click APIMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/main.py"

    %% Layer 3: Controllers
    subgraph "Layer 3: Controllers"
        AuthRDB["AuthController"]:::controller
        StoreRDB["StoreController"]:::controller
        ChatRDB["ChatController"]:::controller

        AuthMongo["AuthController"]:::controller
        StoreMongo["StoreController"]:::controller
        ChatMongo["ChatController"]:::controller
    end

    APIRDB --> AuthRDB
    APIRDB --> StoreRDB
    APIRDB --> ChatRDB

    APIMongo --> AuthMongo
    APIMongo --> StoreMongo
    APIMongo --> ChatMongo

    click AuthRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/routes/auth.py"
    click StoreRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/routes/store.py"
    click ChatRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/routes/chat.py"

    click AuthMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/routes/auth.py"
    click StoreMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/routes/store.py"
    click ChatMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/routes/chat.py"

    %% Layer 4: Business Logic & Utils
    subgraph "Layer 4: Business Logic & Utils"
        UtilsRDB["Utils Module"]:::util
        UtilsMongo["Utils Module"]:::util
    end

    AuthRDB --> UtilsRDB
    StoreRDB --> UtilsRDB
    ChatRDB --> UtilsRDB

    AuthMongo --> UtilsMongo
    StoreMongo --> UtilsMongo
    ChatMongo --> UtilsMongo

    click UtilsRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/utils.py"
    click UtilsMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/utils.py"

    %% Layer 5: Data Access
    subgraph "Layer 5a: Relational Data Access" 
        DBSession["SQLModel Session\n+ SQLite Engine"]:::dataAccess
        ModelsRDB["ORM Models"]:::dataAccess
    end

    subgraph "Layer 5b: Document Data Access"
        MongoConn["MongoClient + Beanie"]:::dataAccess
        ModelsMongo["ODM Models"]:::dataAccess
    end

    UtilsRDB --> DBSession
    UtilsRDB --> ModelsRDB

    UtilsMongo --> MongoConn
    UtilsMongo --> ModelsMongo

    click DBSession "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/database.py"
    click ModelsRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/models.py"
    click MongoConn "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/database.py"
    click ModelsMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/models.py"

    %% Layer 6: Databases
    subgraph "Layer 6: Databases"
        SQLiteDB["SQLite Database"]:::database
        MongoDB["MongoDB"]:::database
    end

    DBSession -->|SQL Queries| SQLiteDB
    MongoConn -->|NoSQL Operations| MongoDB

    %% Layer 7: External Services & Seed
    subgraph "Layer 7: External Services & Bootstrapping"
        Gemini["Google Gemini API"]:::external
        SeedRDB["Seed Script & FAQ"]:::script
        SeedMongo["Seed Script & FAQ"]:::script
        FAQ_RDB["datasets/faq.csv"]:::database
        FAQ_Mongo["datasets/faq.csv"]:::database
    end

    ChatRDB -->|RAG Query| Gemini
    ChatMongo -->|RAG Query| Gemini

    click SeedRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/seed.py"
    click SeedMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/seed.py"
    click FAQ_RDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/datasets/faq.csv"
    click FAQ_Mongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/datasets/faq.csv"

    SeedRDB --> ModelsRDB
    SeedRDB --> SQLiteDB

    SeedMongo --> ModelsMongo
    SeedMongo --> MongoDB

    %% Legend / Supporting
    subgraph "Supporting Files"
        RequirementsRDB["requirements.txt"]:::util
        RequirementsMongo["requirements.txt"]:::util
        Readme["README.md"]:::util
    end

    click RequirementsRDB "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-rdb/requirements.txt"
    click RequirementsMongo "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/ecommerce-mongodb/requirements.txt"
    click Readme "https://github.com/jjoenasr/fastapi-ecommerce/blob/main/README.md"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064;
    classDef api fill:#BBDEFB,stroke:#0D47A1;
    classDef controller fill:#C8E6C9,stroke:#1B5E20;
    classDef util fill:#ECEFF1,stroke:#37474F;
    classDef dataAccess fill:#DCEDC8,stroke:#33691E;
    classDef database fill:#FFF9C4,stroke:#F57F17,shape:cylinder;
    classDef external fill:#FFE0B2,stroke:#E65100,shape:cylinder;
    classDef script fill:#F3E5F5,stroke:#4A148C;
```
