# rishabhporwal/rag-chat-storage architecture

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

- Interactive diagram: https://gitdiagram.com/rishabhporwal/rag-chat-storage
- Repository: https://github.com/rishabhporwal/rag-chat-storage

## Overview

##### Project Type and Purpose
- This is a backend microservice built with FastAPI, intended to store and manage chat sessions/messages for a Retrieval-Augmented Generation chatbot.
- It exposes RESTful HTTP endpoints for session/message CRUD, pagination, favoriting, and renaming.

##### File Structure
- Top-level: configuration files (.env.example, Dockerfile, docker-compose.yml), entrypoint script (wait-for-postgres.sh), and tests.
- app/api/routes: HTTP route handlers (chat_session.py, chat_message.py).
- app/core: cross-cutting concerns (config, logging, rate limiting, security).
- app/db: database setup (SQLAlchemy base, init_db script, async session factory) and ORM models.
- app/schemas: Pydantic request/response schemas.
- app/services: business logic for sessions and messages.
- scripts/init_db.py: one-off DB initialization.
- Tests verify service layer.

##### Extract Key Architectural Insights from README
- Async design: FastAPI + asyncpg + SQLAlchemy (async)
- Containerized with Docker Compose: app container, Postgres container, PG Admin
- Environment-driven config (DATABASE_URL, RATE_LIMIT, API_KEY, LOG_LEVEL)

##### Main Components & Boundaries
1) Client / External Caller
- Any frontend or other microservice making HTTP calls.
2) API Layer (FastAPI / uvicorn)
- app/main.py launches the server.
- Routers in app/api/routes handle HTTP requests.
3) Core Utilities
- Configuration loader
- Logging
- Security (API key auth)
- Rate limiter
4) Business Logic Layer
- session_service & message_service implement use cases.
5) Data Access Layer
- SQLAlchemy async Session factory
- ORM models (chat_session, chat_message)
- scripts/init_db / app/db/init_db.py for migrations/seed
6) PostgreSQL Database
- Separate container instance (docker-compose).
7) Supporting Tools
- PG Admin (GUI in its own container)
- wait-for-postgres.sh ensures DB readiness

##### Component Interactions & Data Flows
- Client → (HTTP+JSON) → FastAPI Router
- Router applies security & rate-limit (via core/security, core/rate_limiter).
- Router → Pydantic Schema validation (app/schemas)
- Router → Service Layer (session_service or message_service)
- Service → Data Access Layer
- Obtain async DB session → perform CRUD via SQLAlchemy models → commit/return results
- Service → Router → JSON Response → Client

##### Architectural Patterns & Principles
- Layered (API → Services → Data) ensuring separation of concerns.
- Async I/O throughout (FastAPI, asyncpg, SQLAlchemy).
- Configuration via environment variables for 12-factor compliance.
- Containerized deployment (Docker Compose) for isolation.

##### Technologies & Frameworks to Annotate
- FastAPI / uvicorn
- Pydantic Schemas
- SQLAlchemy (Async) + asyncpg
- PostgreSQL
- Docker & Docker Compose
- Python (3.11+)

##### Final Checklist
- [ ] Call out key frameworks (FastAPI, SQLAlchemy).
- [ ] Show Docker Compose container boundaries and network.
- [ ] Note the wait-for-postgres startup step as a small annotation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client / Frontend"]:::external

    %% Docker Compose Network
    subgraph "Docker Network"
        direction TB
        %% Microservice Container
        subgraph "RAG Chat Storage Microservice"
            direction TB

            %% API Layer
            subgraph "API Layer (FastAPI)" 
                direction TB
                Main["app/main.py\n(FastAPI Uvicorn)"]:::api
                CSR["ChatSessionRouter\n(app/api/routes/chat_session.py)"]:::api
                CMR["ChatMessageRouter\n(app/api/routes/chat_message.py)"]:::api
                Config["Config Loader\n(app/core/config.py)"]:::core
                Logging["Logging Utility\n(app/core/logging.py)"]:::core
                Security["API Key Auth\n(app/core/security.py)"]:::core
                RateLimiter["Rate Limiter\n(app/core/rate_limiter.py)"]:::core
            end

            %% Service Layer
            subgraph "Service Layer"
                direction TB
                SessionService["SessionService\n(app/services/session_service.py)"]:::service
                MessageService["MessageService\n(app/services/message_service.py)"]:::service
            end

            %% Data Access Layer
            subgraph "Data Access Layer"
                direction TB
                SessionFactory["AsyncSessionFactory\n(app/db/session.py)"]:::data
                BaseInit["Base & Models Init\n(app/db/base.py)"]:::data
                DBInit["DB Init Script\n(app/db/init_db.py)"]:::data
                subgraph "ORM Models"
                    direction TB
                    ChatSessionModel["ChatSession Model\n(app/db/models/chat_session.py)"]:::data
                    ChatMessageModel["ChatMessage Model\n(app/db/models/chat_message.py)"]:::data
                end
            end

        end

        %% Postgres Container
        PostgreSQL["PostgreSQL\n(Container)"]:::db

        %% PG Admin Container
        PGAdmin["PG Admin\n(Container)"]:::external
    end

    %% One-off Init Script
    ScriptsInit["scripts/init_db.py\n(One-off DB Init)"]:::util

    %% Env & Dockerfiles
    EnvExample[".env.example"]:::util
    Dockerfile["Dockerfile"]:::util
    Compose["docker-compose.yml"]:::util
    WaitScript["wait-for-postgres.sh"]:::util

    %% Connections
    Client -->|"HTTP Request"| Main
    Main --> CSR
    Main --> CMR
    CSR -->|"Validate & Auth"| Security
    CSR -->|"Rate Limiting"| RateLimiter
    CMR -->|"Validate & Auth"| Security
    CMR -->|"Rate Limiting"| RateLimiter

    CSR -->|"uses Pydantic"| Config
    CMR -->|"uses Pydantic"| Config

    CSR --> SessionService
    CMR --> MessageService

    SessionService --> SessionFactory
    MessageService --> SessionFactory
    SessionFactory --> PostgreSQL
    SessionService --> ChatSessionModel
    MessageService --> ChatMessageModel

    BaseInit --> SessionFactory
    DBInit --> SessionFactory
    DBInit --> BaseInit

    ScriptsInit --> PostgreSQL

    %% Return flows
    SessionService --> CSR
    MessageService --> CMR
    CSR -->|HTTP Response| Client
    CMR -->|HTTP Response| Client

    %% Click Events
    click Main "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/main.py"
    click CSR "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/api/routes/chat_session.py"
    click CMR "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/api/routes/chat_message.py"
    click Config "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/core/config.py"
    click Logging "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/core/logging.py"
    click Security "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/core/security.py"
    click RateLimiter "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/core/rate_limiter.py"
    click SessionService "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/services/session_service.py"
    click MessageService "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/services/message_service.py"
    click BaseInit "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/db/base.py"
    click DBInit "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/db/init_db.py"
    click SessionFactory "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/db/session.py"
    click ChatSessionModel "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/db/models/chat_session.py"
    click ChatMessageModel "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/db/models/chat_message.py"
    click ScriptsInit "https://github.com/rishabhporwal/rag-chat-storage/blob/master/scripts/init_db.py"
    click Compose "https://github.com/rishabhporwal/rag-chat-storage/blob/master/docker-compose.yml"
    click Dockerfile "https://github.com/rishabhporwal/rag-chat-storage/tree/master/Dockerfile"
    click EnvExample "https://github.com/rishabhporwal/rag-chat-storage/blob/master/.env.example"
    click WaitScript "https://github.com/rishabhporwal/rag-chat-storage/blob/master/app/wait-for-postgres.sh"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#999,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#007bff,stroke-width:2px,stroke-dasharray: 5 5
    classDef core fill:#e0f7fa,stroke:#006064,stroke-width:2px
    classDef service fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef data fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef db fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef util fill:#f8d7da,stroke:#721c24,stroke-width:2px
```
