# jan-dyndor/ai-chatbot architecture

> Architecture diagram of the GitHub repository jan-dyndor/ai-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jan-dyndor/ai-chatbot
- Repository: https://github.com/jan-dyndor/ai-chatbot

## Overview

This is a local AI chatbot with a Streamlit interface, FastAPI backend, PostgreSQL persistence, and Ollama-backed model generation. Users register or log in, then create chats, load history, choose a model, and submit messages; the backend streams model output and persists the exchange. Conversation titles and available models are also supported. The map includes authentication, per-conversation locking, and request middleware. Some route and page implementations were not sampled, so their connections reflect the documented layered design; planned capabilities are omitted.

Main entry points: [`src/backend/api/router/v1.py`](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/api/router/v1.py) (API Routes), [`src/backend/main.py`](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/main.py) (App Setup), [`src/backend/service/chat_service.py`](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/service/chat_service.py) (Chat Service), [`src/backend/chat_bot/client.py`](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/chat_bot/client.py) (Model Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit UI"]
  node_frontend["UI Entry<br/>[main.py]"]
  node_chatpage["Chat Page<br/>[chatbot_page.py]"]
  node_loginpage["Login Page<br/>[login_page.py]"]
  node_registerpage["Register Page<br/>[register_page.py]"]
end

subgraph group_api["FastAPI Backend"]
  node_backend["App Setup<br/>[main.py]"]
  node_routes["API Routes<br/>[v1.py]"]
  node_dependencies["Dependencies<br/>[depends.py]"]
  node_middleware["Request Middleware"]
  node_logging["Logging Middleware"]
end

subgraph group_identity["Identity"]
  node_auth["Auth Service<br/>[auth.py]"]
  node_passwords["Password Hashing<br/>[passwords.py]"]
  node_userservice["User Service<br/>[user_service.py]"]
end

subgraph group_conversation["Chat Services"]
  node_chatservice["Chat Service<br/>[chat_service.py]"]
  node_chatbot["Model Client<br/>[client.py]"]
  node_locks["Conversation Locks"]
end

subgraph group_persistence["Persistence"]
  node_userrepo["User Repository<br/>[user_repository.py]"]
  node_chatrepo["Chat Repository<br/>[chat_repository.py]"]
  node_db["Database Setup<br/>[db.py]"]
  node_models["Data Models<br/>[models.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_ollama["Ollama"]

node_user -->|"uses"| node_frontend
node_frontend -->|"routes unauthenticated"| node_loginpage
node_frontend -->|"routes authenticated"| node_chatpage
node_loginpage -->|"sends login"| node_routes
node_registerpage -->|"sends registration"| node_routes
node_chatpage -->|"requests chats"| node_routes
node_routes -->|"resolves services"| node_dependencies
node_routes -->|"authenticates"| node_auth
node_routes -->|"dispatches chat"| node_chatservice
node_routes -->|"dispatches registration"| node_userservice
node_backend -->|"registers router"| node_routes
node_backend -->|"installs"| node_middleware
node_backend -->|"installs"| node_logging
node_backend -->|"initializes"| node_db
node_backend -->|"creates manager"| node_locks
node_auth -->|"looks up users"| node_userrepo
node_auth -->|"verifies passwords"| node_passwords
node_userservice -->|"hashes password"| node_passwords
node_userservice -->|"creates user"| node_userrepo
node_chatservice -->|"reads and writes"| node_chatrepo
node_chatservice -->|"generates responses"| node_chatbot
node_chatservice -->|"creates titles"| node_chatbot
node_chatbot -->|"streams generation"| node_ollama
node_chatbot -->|"lists models"| node_ollama
node_chatrepo -->|"queries"| node_models
node_userrepo -->|"queries"| node_models
node_db -->|"connects"| node_postgres
node_chatrepo -->|"persists chat data"| node_postgres
node_userrepo -->|"persists accounts"| node_postgres
node_routes -->|"streams response"| node_chatpage

click node_frontend "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/main.py"
click node_chatpage "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/chatbot_page.py"
click node_loginpage "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/login_page.py"
click node_registerpage "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/register_page.py"
click node_backend "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/main.py"
click node_routes "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/api/router/v1.py"
click node_dependencies "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/dependencies/depends.py"
click node_middleware "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/middleware/request_id_middleware.py"
click node_logging "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/middleware/logging_middleware.py"
click node_auth "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/authentication/auth.py"
click node_passwords "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/authentication/passwords.py"
click node_userservice "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/service/user_service.py"
click node_userrepo "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/user_repository.py"
click node_chatservice "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/service/chat_service.py"
click node_chatbot "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/chat_bot/client.py"
click node_locks "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/core/concurency/conversation_thread_lock.py"
click node_chatrepo "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/chat_repository.py"
click node_db "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/db.py"
click node_models "https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_chatpage,node_loginpage,node_registerpage,node_user toneBlue
class node_backend,node_routes,node_dependencies,node_middleware,node_logging,node_postgres toneAmber
class node_auth,node_passwords,node_userservice toneMint
class node_chatservice,node_chatbot,node_locks toneRose
class node_userrepo,node_chatrepo,node_db,node_models,node_ollama toneIndigo
```

## Components

### Streamlit UI

- [UI Entry](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/main.py): `src/frontend/main.py`
- [Chat Page](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/chatbot_page.py): `src/frontend/pages/chatbot_page.py`
- [Login Page](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/login_page.py): `src/frontend/pages/login_page.py`
- [Register Page](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/frontend/pages/register_page.py): `src/frontend/pages/register_page.py`

### FastAPI Backend

- [App Setup](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/main.py): `src/backend/main.py`
- [API Routes](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/api/router/v1.py): `src/backend/api/router/v1.py`
- [Dependencies](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/dependencies/depends.py): `src/backend/dependencies/depends.py`
- [Request Middleware](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/middleware/request_id_middleware.py): `src/backend/middleware/request_id_middleware.py`
- [Logging Middleware](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/middleware/logging_middleware.py): `src/backend/middleware/logging_middleware.py`

### Identity

- [Auth Service](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/authentication/auth.py): `src/backend/authentication/auth.py`
- [Password Hashing](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/authentication/passwords.py): `src/backend/authentication/passwords.py`
- [User Service](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/service/user_service.py): `src/backend/service/user_service.py`

### Chat Services

- [Chat Service](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/service/chat_service.py): `src/backend/service/chat_service.py`
- [Model Client](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/chat_bot/client.py): `src/backend/chat_bot/client.py`
- [Conversation Locks](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/core/concurency/conversation_thread_lock.py): `src/backend/core/concurency/conversation_thread_lock.py`

### Persistence

- [User Repository](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/user_repository.py): `src/backend/database/user_repository.py`
- [Chat Repository](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/chat_repository.py): `src/backend/database/chat_repository.py`
- [Database Setup](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/db.py): `src/backend/database/db.py`
- [Data Models](https://github.com/jan-dyndor/ai-chatbot/blob/main/src/backend/database/models.py): `src/backend/database/models.py`

### Other components

- **User**
- **PostgreSQL**
- **Ollama**

## Connections

- User → UI Entry: uses
- UI Entry → Login Page: routes unauthenticated
- UI Entry → Chat Page: routes authenticated
- Login Page → API Routes: sends login
- Register Page → API Routes: sends registration
- Chat Page → API Routes: requests chats
- API Routes → Dependencies: resolves services
- API Routes → Auth Service: authenticates
- API Routes → Chat Service: dispatches chat
- API Routes → User Service: dispatches registration
- App Setup → API Routes: registers router
- App Setup → Request Middleware: installs
- App Setup → Logging Middleware: installs
- App Setup → Database Setup: initializes
- App Setup → Conversation Locks: creates manager
- Auth Service → User Repository: looks up users
- Auth Service → Password Hashing: verifies passwords
- User Service → Password Hashing: hashes password
- User Service → User Repository: creates user
- Chat Service → Chat Repository: reads and writes
- Chat Service → Model Client: generates responses
- Chat Service → Model Client: creates titles
- Model Client → Ollama: streams generation
- Model Client → Ollama: lists models
- Chat Repository → Data Models: queries
- User Repository → Data Models: queries
- Database Setup → PostgreSQL: connects
- Chat Repository → PostgreSQL: persists chat data
- User Repository → PostgreSQL: persists accounts
- API Routes → Chat Page: streams response