# filigott/dat640-project architecture

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

- Interactive diagram: https://gitdiagram.com/filigott/dat640-project
- Repository: https://github.com/filigott/dat640-project

## Overview

##### Project type and purpose
- This is a full-stack, conversational music recommendation application.
- Frontend: Vite + React (TypeScript) SPA with chat widget, playlist and song list components.
- Backend: FastAPI service exposing REST and WebSocket endpoints, using SQLAlchemy/Alembic for PostgreSQL persistence, plus a chat-agent layer.
- NLP/NLU: Rasa agent running as a separate service for intent parsing and dialogue management.
- Simulation: A built-in user simulation module for testing chat flows.

##### File structure
- Top-level folders:
- backend_fastAPI/ – FastAPI code, Alembic migrations, Docker Compose for Postgres
- frontend/ – Vite + React application
- rasa_agent/ – Rasa NLU project (actions, data, models, endpoints)
- backend_fastAPI/app/ packages:
- routers/ – HTTP & WebSocket route definitions (song, playlist, seed, client-only, chat)
- repository/ – data access layer (Repository pattern over SQLAlchemy models)
- chat_agent/ & chat_agent_service/ – orchestration and external service calls for chat
- simulation/ – user‐simulator code driving WebSocket client for testing
- database.py, init_db.py, models.py, schemas.py – DB setup and ORM mapping
- Configuration/build files:
- backend_fastAPI/alembic/ – DB migration scripts
- backend_fastAPI/postgres/docker-compose.yml – Postgres container definition
- frontend/vite.config.ts, tsconfig*.json, package.json – frontend build/dev config
- rasa_agent/*.yml, models/ – Rasa config, training data, and pre-built model
- run.sh, requirements.txt – top-level orchestration and Python deps

##### Key points from README
- Services to run: Docker Compose for Postgres, FastAPI (uvicorn), React (npm run dev), Rasa (rasa run).
- Endpoints: REST (8000), WebSocket (8000), frontend (8001), Rasa API (5005), Adminer (8080).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Tier
    subgraph "Presentation Tier"
        direction TB
        Browser["Client Browser"]:::frontend
        ReactMain["frontend/src/main.tsx"]:::frontend
        AppComp["frontend/src/App.tsx"]:::frontend
        ChatWidget["CustomChatWidget"]:::frontend
        PlaylistComp["Playlist Component"]:::frontend
        SonglistComp["Songlist Component"]:::frontend
        Browser --> ReactMain
        ReactMain --> AppComp
        AppComp --> ChatWidget
        AppComp --> PlaylistComp
        AppComp --> SonglistComp
    end

    %% Application Tier
    subgraph "Application Tier (FastAPI)" 
        direction TB
        Main["backend_fastAPI/app/main.py"]:::backend
        Uvicorn["backend_fastAPI/uvicorn_run.py"]:::backend

        subgraph Routers
            direction TB
            SongRoutes["Song Routes"]:::backend
            PlaylistRoutes["Playlist Routes"]:::backend
            SeedRoutes["Seed Routes"]:::backend
            ClientOnly["Client-Only Routes"]:::backend
            WSRoutes["WebSocket Routes"]:::backend
        end

        ChatMediator["backend_fastAPI/app/chat_mediator.py"]:::backend
        ChatService["chat_agent_service.ChatAgentService"]:::backend
        ChatAgent["chat_agent.ChatAgent"]:::backend

        subgraph "Data & ORM"
            direction TB
            DBConn["database.py"]:::backend
            InitDB["init_db.py"]:::backend
            Models["models.py"]:::backend
            Schemas["schemas.py"]:::backend
            Repository["repository.py"]:::backend
        end

        subgraph Simulation
            direction TB
            SimRun["run_user_sim.py"]:::backend
            SimAgent["user_sim_agent.py"]:::backend
            SimProfiles["user_sim_profiles.py"]:::backend
            SimUtils["user_sim_utils.py"]:::backend
            WSSim["ws_sim_client.py"]:::backend
        end

        Main --> SongRoutes
        Main --> PlaylistRoutes
        Main --> SeedRoutes
        Main --> ClientOnly
        Main --> WSRoutes
        Main --> ChatMediator
        Main --> DBConn
        Main --> InitDB

        SongRoutes --> Repository
        PlaylistRoutes --> Repository
        SeedRoutes --> InitDB
        ClientOnly --> Repository

        WSRoutes --> ChatMediator
        WSSim --> WSRoutes

        ChatMediator --> ChatService
        ChatService --> ChatAgent

        Repository --> DBConn
        DBConn --> Models
        Models --> Schemas
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        PostgresDB["PostgreSQL DB"]:::database
        Alembic["Alembic Migrations"]:::database
        DockerCompose["docker-compose.yml"]:::database
        Repository --> PostgresDB
        Alembic --> PostgresDB
        DockerCompose --> PostgresDB
    end

    %% External NLU Tier
    Rasa["Rasa NLU Server"]:::external

    %% Interactions
    Browser -->|"HTTP REST"| SongRoutes
    Browser -->|"HTTP REST"| PlaylistRoutes
    Browser -->|"HTTP REST"| SeedRoutes
    Browser -->|"WebSocket Chat"| WSRoutes
    ChatAgent -->|"HTTP API"| Rasa
    WSRoutes -->|"WebSocket Response"| Browser
    SimRun --> WSSim

    %% Click events
    click ReactMain "https://github.com/filigott/dat640-project/blob/main/frontend/src/main.tsx"
    click AppComp "https://github.com/filigott/dat640-project/blob/main/frontend/src/App.tsx"
    click ChatWidget "https://github.com/filigott/dat640-project/blob/main/frontend/src/components/CustomChatWidget/CustomChatWidget.tsx"
    click PlaylistComp "https://github.com/filigott/dat640-project/blob/main/frontend/src/components/Playlist.tsx"
    click SonglistComp "https://github.com/filigott/dat640-project/blob/main/frontend/src/components/Songlist.tsx"
    click Main "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/main.py"
    click Uvicorn "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/uvicorn_run.py"
    click SongRoutes "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/routers/song_routes.py"
    click PlaylistRoutes "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/routers/playlist_routes.py"
    click SeedRoutes "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/routers/seed_routes.py"
    click ClientOnly "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/routers/client_only_routes.py"
    click WSRoutes "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/routers/websocket_routes.py"
    click ChatMediator "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/chat_mediator.py"
    click ChatService "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/chat_agent_service/chat_agent_service.py"
    click ChatAgent "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/chat_agent/chat_agent.py"
    click DBConn "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/database.py"
    click InitDB "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/init_db.py"
    click Models "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/models.py"
    click Schemas "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/schemas.py"
    click Repository "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/repository/repository.py"
    click SimRun "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/simulation/run_user_sim.py"
    click SimAgent "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/simulation/user_sim_agent.py"
    click SimProfiles "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/simulation/user_sim_profiles.py"
    click SimUtils "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/simulation/user_sim_utils.py"
    click WSSim "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/app/simulation/ws_sim_client.py"
    click Alembic "https://github.com/filigott/dat640-project/tree/main/backend_fastAPI/alembic/"
    click DockerCompose "https://github.com/filigott/dat640-project/blob/main/backend_fastAPI/postgres/docker-compose.yml"
    click Rasa "https://github.com/filigott/dat640-project/tree/main/rasa_agent/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#E6F4EA,stroke:#257A32,stroke-width:1px
    classDef database fill:#FFF4CF,stroke:#CC9C00,stroke-width:1px
    classDef external fill:#FFE8D6,stroke:#D9822B,stroke-width:1px
```
