# albkue/ai-mood-journal architecture

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

- Interactive diagram: https://gitdiagram.com/albkue/ai-mood-journal
- Repository: https://github.com/albkue/ai-mood-journal

## Overview

AI Mood Journal combines a Flutter client, FastAPI account and journal APIs, relational persistence, and NLP-driven mood analysis and insights. The documented user workflow is to authenticate, create journal entries, and receive mood analysis and personalized trend insights; the repository excerpts show backend and ML internals, but not the Flutter application’s Dart runtime. The README documents the cross-platform client and recommendation capability, while the source index identifies ML modules whose detailed implementations are only partly excerpted.

Main entry points: [`ml/services/entry_analyzer.py`](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/entry_analyzer.py) (Entry analyzer), [`backend/fastapi_server/app/main.py`](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/main.py) (API application), [`ml/services/insights_service.py`](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/insights_service.py) (Insights service), [`backend/fastapi_server/app/routers/auth.py`](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/auth.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobile["Flutter app"]
end

subgraph group_api["Backend API"]
  node_api_entry["API application<br/>[main.py]"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_journal_routes["Journal endpoints<br/>[journal.py]"]
  node_ml_routes["ML endpoints<br/>[ml.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_journal_service["Journal service<br/>[journal_service.py]"]
  node_auth_core["Token security<br/>[auth.py]"]
  node_input_safety["Input sanitization<br/>[sanitization.py]"]
  node_api_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_storage["Persistence"]
  node_journal_repo["Journal repository"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_base_repo["Repository base<br/>[base_repository.py]"]
  node_orm_models["User and entry models<br/>[models.py]"]
  node_db_config["Database sessions<br/>[database.py]"]
end

subgraph group_analysis["ML analysis"]
  node_entry_analyzer["Entry analyzer<br/>[entry_analyzer.py]"]
  node_emotion_predictor["Emotion prediction"]
  node_topic_modeler["Topic modeling<br/>[topic_modeler.py]"]
  node_insights_aggregator["Insights aggregation"]
  node_insights_service["Insights service"]
  node_text_prep["Text preprocessing"]
  node_model_training["LDA training<br/>[train_lda.py]"]
end

node_user(("Journal user"))
node_postgres[("PostgreSQL")]

node_user -.->|"uses"| node_mobile
node_mobile -.->|"requests API"| node_api_entry
node_api_entry -->|"registers routes"| node_auth_routes
node_api_entry -->|"registers routes"| node_journal_routes
node_api_entry -->|"registers routes"| node_ml_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_service -->|"queries users"| node_user_repo
node_auth_service -->|"creates tokens"| node_auth_core
node_auth_routes -->|"sanitizes input"| node_input_safety
node_journal_service -->|"manages entries"| node_journal_repo
node_journal_repo -->|"inherits CRUD"| node_base_repo
node_user_repo -->|"inherits CRUD"| node_base_repo
node_base_repo -->|"uses database base"| node_db_config
node_orm_models -->|"declares mapped models"| node_db_config
node_db_config -->|"connects to"| node_postgres
node_journal_routes -->|"integrates analysis"| node_entry_analyzer
node_journal_routes -->|"integrates insights"| node_insights_service
node_ml_routes -->|"integrates insights"| node_insights_service
node_insights_service -->|"delegates analysis"| node_entry_analyzer
node_insights_service -->|"delegates aggregation"| node_insights_aggregator
node_entry_analyzer -->|"uses predictor"| node_emotion_predictor
node_entry_analyzer -->|"uses modeler"| node_topic_modeler
node_entry_analyzer -->|"uses aggregation"| node_insights_aggregator
node_model_training -->|"trains topic model"| node_topic_modeler

click node_mobile "https://github.com/albkue/ai-mood-journal/tree/main/frontend/flutter_app"
click node_api_entry "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/main.py"
click node_auth_routes "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/auth.py"
click node_journal_routes "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/journal.py"
click node_ml_routes "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/ml.py"
click node_auth_service "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/services/auth_service.py"
click node_journal_service "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/services/journal_service.py"
click node_auth_core "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/auth.py"
click node_input_safety "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/utils/sanitization.py"
click node_api_schemas "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/schemas.py"
click node_journal_repo "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/journal_repository.py"
click node_user_repo "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/user_repository.py"
click node_base_repo "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/base_repository.py"
click node_orm_models "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/models.py"
click node_db_config "https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/database.py"
click node_entry_analyzer "https://github.com/albkue/ai-mood-journal/blob/main/ml/services/entry_analyzer.py"
click node_emotion_predictor "https://github.com/albkue/ai-mood-journal/blob/main/ml/services/emotion_predictor.py"
click node_topic_modeler "https://github.com/albkue/ai-mood-journal/blob/main/ml/services/topic_modeler.py"
click node_insights_aggregator "https://github.com/albkue/ai-mood-journal/blob/main/ml/services/insights_aggregator.py"
click node_insights_service "https://github.com/albkue/ai-mood-journal/blob/main/ml/services/insights_service.py"
click node_text_prep "https://github.com/albkue/ai-mood-journal/blob/main/ml/preprocessing/text_preprocessor.py"
click node_model_training "https://github.com/albkue/ai-mood-journal/blob/main/ml/training/train_lda.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_mobile,node_user toneBlue
class node_api_entry,node_auth_routes,node_journal_routes,node_ml_routes,node_auth_service,node_journal_service,node_auth_core,node_input_safety,node_api_schemas,node_postgres toneAmber
class node_journal_repo,node_user_repo,node_base_repo,node_orm_models,node_db_config toneMint
class node_entry_analyzer,node_emotion_predictor,node_topic_modeler,node_insights_aggregator,node_insights_service,node_text_prep,node_model_training toneRose
```

## Components

### Mobile client

- [Flutter app](https://github.com/albkue/ai-mood-journal/tree/main/frontend/flutter_app): `frontend/flutter_app`

### Backend API

- [API application](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/main.py): `backend/fastapi_server/app/main.py`
- [Auth endpoints](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/auth.py): `backend/fastapi_server/app/routers/auth.py`
- [Journal endpoints](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/journal.py): `backend/fastapi_server/app/routers/journal.py`
- [ML endpoints](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/routers/ml.py): `backend/fastapi_server/app/routers/ml.py`
- [Authentication service](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/services/auth_service.py): `backend/fastapi_server/app/services/auth_service.py`
- [Journal service](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/services/journal_service.py): `backend/fastapi_server/app/services/journal_service.py`
- [Token security](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/auth.py): `backend/fastapi_server/app/auth.py`
- [Input sanitization](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/utils/sanitization.py): `backend/fastapi_server/app/utils/sanitization.py`
- [API schemas](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/schemas.py): `backend/fastapi_server/app/schemas.py`

### Persistence

- [Journal repository](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/journal_repository.py): `backend/fastapi_server/app/repositories/journal_repository.py`
- [User repository](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/user_repository.py): `backend/fastapi_server/app/repositories/user_repository.py`
- [Repository base](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/repositories/base_repository.py): `backend/fastapi_server/app/repositories/base_repository.py`
- [User and entry models](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/models.py): `backend/fastapi_server/app/models.py`
- [Database sessions](https://github.com/albkue/ai-mood-journal/blob/main/backend/fastapi_server/app/database.py): `backend/fastapi_server/app/database.py`

### ML analysis

- [Entry analyzer](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/entry_analyzer.py): `ml/services/entry_analyzer.py`
- [Emotion prediction](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/emotion_predictor.py): `ml/services/emotion_predictor.py`
- [Topic modeling](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/topic_modeler.py): `ml/services/topic_modeler.py`
- [Insights aggregation](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/insights_aggregator.py): `ml/services/insights_aggregator.py`
- [Insights service](https://github.com/albkue/ai-mood-journal/blob/main/ml/services/insights_service.py): `ml/services/insights_service.py`
- [Text preprocessing](https://github.com/albkue/ai-mood-journal/blob/main/ml/preprocessing/text_preprocessor.py): `ml/preprocessing/text_preprocessor.py`
- [LDA training](https://github.com/albkue/ai-mood-journal/blob/main/ml/training/train_lda.py): `ml/training/train_lda.py`

### Other components

- **Journal user**
- **PostgreSQL**

## Connections

- Journal user → Flutter app: uses (evidence: `README.md`)
- Flutter app → API application: requests API
- API application → Auth endpoints: registers routes (evidence: `backend/fastapi_server/app/main.py`)
- API application → Journal endpoints: registers routes (evidence: `backend/fastapi_server/app/main.py`)
- API application → ML endpoints: registers routes (evidence: `backend/fastapi_server/app/main.py`)
- Auth endpoints → Authentication service: calls (evidence: `backend/fastapi_server/app/routers/auth.py`)
- Authentication service → User repository: queries users (evidence: `backend/fastapi_server/app/services/auth_service.py`)
- Authentication service → Token security: creates tokens (evidence: `backend/fastapi_server/app/services/auth_service.py`)
- Auth endpoints → Input sanitization: sanitizes input (evidence: `backend/fastapi_server/app/routers/auth.py`)
- Journal service → Journal repository: manages entries (evidence: `backend/fastapi_server/app/services/journal_service.py`)
- Journal repository → Repository base: inherits CRUD (evidence: `backend/fastapi_server/app/repositories/journal_repository.py`)
- User repository → Repository base: inherits CRUD (evidence: `backend/fastapi_server/app/repositories/user_repository.py`)
- Repository base → Database sessions: uses database base (evidence: `backend/fastapi_server/app/repositories/base_repository.py`)
- User and entry models → Database sessions: declares mapped models (evidence: `backend/fastapi_server/app/models.py`)
- Database sessions → PostgreSQL: connects to (evidence: `backend/fastapi_server/app/database.py`)
- Journal endpoints → Entry analyzer: integrates analysis (evidence: `README.md`)
- Journal endpoints → Insights service: integrates insights (evidence: `README.md`)
- ML endpoints → Insights service: integrates insights (evidence: `README.md`)
- Insights service → Entry analyzer: delegates analysis (evidence: `ml/services/insights_service.py`)
- Insights service → Insights aggregation: delegates aggregation (evidence: `ml/services/insights_service.py`)
- Entry analyzer → Emotion prediction: uses predictor (evidence: `ml/services/entry_analyzer.py`)
- Entry analyzer → Topic modeling: uses modeler (evidence: `ml/services/entry_analyzer.py`)
- Entry analyzer → Insights aggregation: uses aggregation (evidence: `ml/services/entry_analyzer.py`)
- LDA training → Topic modeling: trains topic model (evidence: `ml/training/train_lda.py`)
