# d4ndr4d3/toulmin architecture

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

- Interactive diagram: https://gitdiagram.com/d4ndr4d3/toulmin
- Repository: https://github.com/d4ndr4d3/toulmin

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered social media application (“Toulmin Argumentation Platform”) built with React on the frontend and FastAPI on the backend.
- It ingests user posts (tweets/comments), performs real-time argument analysis (Toulmin model via GPT-4o), and visualizes argument structures. It also provides AI-driven writing assistance and discovery services (vector embeddings + semantic search).

##### File Structure
– Top-level directories:
- devcontainer & Dockerfile(s): IDE and container setup
- backend/: FastAPI application (routes, services, models, websockets)
- docker-compose.yml & nginx.conf: Docker orchestration and reverse proxy
- scripts/: helper scripts for deployment/testing
- tests/: automated tests
– Backend layering:
- app/routes: HTTP endpoints (authentication, tweets, comments, discovery, suggestions)
- app/services: business logic (embeddings, LLM calls, WebSocket coordination)
- database.py/models.py: MongoDB integration and Pydantic schemas
– Frontend structure:
- src/components: UI modules (TweetComposer, ToulminDiagram, WritingAssistant, AuthModal)
- public: static assets, index.html
– Configuration: environment files (.env, docker.env), Dockerfiles, CI workflows.

##### README for Additional Insights
– Tech stack: React 19 + TailwindCSS, FastAPI 3.11, MongoDB Atlas, Qdrant Cloud, OpenAI GPT-4o, JWT auth, WebSockets.
– Key flows:
- HTTP REST for CRUD + AI-powered suggestions
- Vector DB calls for semantic search
– Deployment options: standalone Docker, Docker Compose, cloud (Docker Hub image).

a. Main Components
1. Client Browser (React App)
2. NGINX Reverse Proxy (in front of backend)
3. FastAPI Backend
– Authentication Module (JWT)
– API Layer (routes: users, tweets, comments, discovery, suggestions)
– Services Layer
- LLM Service (OpenAI GPT-4o calls)
- Embeddings Service (Qdrant vector DB)
- WebSocket Manager (real-time updates)
– Data Layer (MongoDB)
4. External Services
– OpenAI API
– MongoDB Atlas
– Qdrant Cloud
b. Relationships & Interactions
- Browser → HTTP/HTTPS → NGINX → FastAPI routes
- FastAPI → MongoDB (CRUD on users, tweets, analysis results)
- FastAPI → Qdrant (store/query embeddings)
- FastAPI → OpenAI (Toulmin analysis, suggestions)
c. Architectural Patterns & Principles
- Layered Architecture (presentation, API, services, data)
- Single‐process monolith backend with modular services
- Containerization (Docker + docker-compose) for consistent environments
- API Gateway/Reverse Proxy (NGINX)
- Real-time messaging via WebSocket channel
d. Key Technologies
- Frontend: React 19, TailwindCSS, React Flow
- Backend: FastAPI, Python 3.11, Pydantic, WebSockets
- Databases: MongoDB Atlas (document store), Qdrant Cloud (vector store)
- AI: OpenAI GPT-4o
- DevOps: Docker, docker-compose, GitHub Actions, supervisord (devcontainer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ClientBrowser["Client Browser (React App)"]:::frontend
        UIComponents["UI Components\n(TweetComposer, ToulminDiagram,\nWritingAssistant, AuthModal)"]:::frontend
    end

    %% Proxy Layer
    Nginx["NGINX Reverse Proxy"]:::proxy

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        subgraph "API Layer"
            direction TB
            UsersAPI["/api/users"]:::api
            TweetsAPI["/api/tweets"]:::api
            CommentsAPI["/api/comments"]:::api
            DiscoveryAPI["/api/discovery"]:::api
            SuggestionsAPI["/api/suggestions"]:::api
        end
        subgraph "Service Layer"
            direction TB
            LLMService["LLM Service\n(Toulmin Analysis)"]:::service
            SuggestService["Writing Suggestions Service"]:::service
            EmbeddingsService["Embeddings Service"]:::service
            WSManager["WebSocket Manager"]:::service
        end
        subgraph "Data Layer"
            direction TB
            DatabaseIntegration["MongoDB Integration\n&Pydantic Schemas"]:::db
            Qdrant["Qdrant Cloud (Vector DB)"]:::db
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI GPT-4o API"]:::external
        MongoAtlas["MongoDB Atlas"]:::db
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        DockerCompose["docker-compose.yml"]:::deployment
        RootDockerfile["Dockerfile"]:::deployment
        Devcontainer[".devcontainer/Dockerfile"]:::deployment
        EnvConfig["Env Files"]:::deployment
    end

    %% Flows
    ClientBrowser -->|"HTTP/HTTPS"| Nginx
    Nginx -->|"/api/*"| UsersAPI
    UsersAPI -->|calls| LLMService
    Nginx -->|"/api/*"| TweetsAPI
    TweetsAPI -->|calls| EmbeddingsService
    Nginx -->|"/api/*"| CommentsAPI
    Nginx -->|"/api/*"| DiscoveryAPI
    DiscoveryAPI -->|queries| Qdrant
    Nginx -->|"/api/*"| SuggestionsAPI
    SuggestionsAPI -->|calls| SuggestService

    LLMService -->|requests| OpenAI
    EmbeddingsService -->|queries| Qdrant
    DatabaseIntegration -->|CRUD| MongoAtlas
    TweetsAPI -->|CRUD| MongoAtlas
    CommentsAPI -->|CRUD| MongoAtlas
    UsersAPI -->|CRUD| MongoAtlas

    ClientBrowser <-->|WebSocket| WSManager
    WSManager -->|broadcasts| ClientBrowser
    WSManager -->|stores updates| MongoAtlas

    %% Deployment to Services
    DockerCompose -->|orchestrates| Nginx
    DockerCompose -->|orchestrates| ClientBrowser
    DockerCompose -->|orchestrates| UsersAPI
    EnvConfig -->|provides| UsersAPI

    %% Click Events
    click ClientBrowser "https://github.com/d4ndr4d3/toulmin/tree/main/frontend/"
    click UIComponents "https://github.com/d4ndr4d3/toulmin/blob/main/frontend/src/components.js"
    click Nginx "https://github.com/d4ndr4d3/toulmin/blob/main/nginx.conf"
    click UsersAPI "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/routes/users.py"
    click TweetsAPI "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/routes/tweets.py"
    click CommentsAPI "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/routes/comments.py"
    click DiscoveryAPI "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/routes/discovery.py"
    click SuggestionsAPI "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/routes/suggestions.py"
    click WSManager "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/websocket_manager.py"
    click LLMService "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/services/toulmin_analyzer.py"
    click SuggestService "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/services/smart_suggestions_service.py"
    click EmbeddingsService "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/services/embeddings_service.py"
    click DatabaseIntegration "https://github.com/d4ndr4d3/toulmin/blob/main/backend/app/database.py"
    click DockerCompose "https://github.com/d4ndr4d3/toulmin/blob/main/docker-compose.yml"
    click RootDockerfile "https://github.com/d4ndr4d3/toulmin/tree/main/Dockerfile"
    click Devcontainer "https://github.com/d4ndr4d3/toulmin/tree/main/.devcontainer/Dockerfile"
    click EnvConfig "https://github.com/d4ndr4d3/toulmin/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000
    classDef proxy fill:#e0ffff,stroke:#000
    classDef api fill:#cfe2f3,stroke:#000
    classDef service fill:#98fb98,stroke:#000
    classDef db fill:#ffa500,stroke:#000
    classDef external fill:#dda0dd,stroke:#000
    classDef deployment fill:#d3d3d3,stroke:#000
```
