# temirlan-k/ollama-app architecture

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

- Interactive diagram: https://gitdiagram.com/temirlan-k/ollama-app
- Repository: https://github.com/temirlan-k/ollama-app

## Overview

##### Project type and purpose
- This is a backend-only web service implementing Clean Architecture in Python.
- Purpose: provide AI-powered analytics, request processing, and user services via HTTP (REST & GraphQL), backed by multiple data stores, caching, LLM provider integration, observability, and security.

##### File structure
- Four clean layers under src/:
- domain/ (entities, interfaces, exceptions)
- application/ (analytics_service, request_service, user_service)
- infra/ (db: PostgreSQL, MongoDB, Redis; llm_provider; prometheus; grafana; security; sentry)
- presentation/ (API entrypoints: REST v1, GraphQL; Pydantic schemas)
- bootstrap/ holds DI container, configuration, logging, and main.py as entry point.
- Top-level orchestrators: Dockerfile, docker-compose.yml, Makefile, Alembic migrations, requirements.txt.
- tests/ exercise domain and application layers with mocks and real DBs.

##### README for additional insights
- Confirms Clean Architecture: Domain → Application → Infrastructure → Presentation.
- Names key patterns: Dependency Injection (DIContainer), Repository, Unit of Work, Factory.
- Lists external dependencies: PostgreSQL, MongoDB, Redis, FastAPI, JWT, Ollama (LLM), Prometheus, Grafana, Sentry.

##### Main components and interactions
a. Components:
- Presentation Layer:
- REST API (FastAPI Controllers)
- GraphQL API (Resolvers & Schemas)
- Application Layer:
- AnalyticsService
- RequestService
- UserService
- Domain Layer:
- Entities (User, Request, Chat, LLMResponse, Analytics)
- Interfaces (AnalyticsPort, LLMP ort, …)
- Infrastructure Layer:
- PostgreSQL (UserRepo, RequestRepo, UoW)
- MongoDB (AnalyticsRepo)
- Redis Cache (CacheDecorator)
- LLM Provider (Ollama)
- Security (JWT handler, password hashing)
- Observability (Prometheus middleware/metrics, Grafana dashboards, Sentry)
- Bootstrap & Orchestration:
- DI Container wiring
- Configuration & Logging
- main.py → FastAPI app

b. Relationships & data flows:
- HTTP Request → Presentation (REST/GraphQL) → invokes ApplicationService
- ApplicationService uses Domain Interfaces and Entities
- DI Container injects concrete Infra implementations of Interfaces
- Repositories/UoW coordinate transactions with PostgreSQL/MongoDB/Redis
- LLMProvider calls external LLM model
- Prometheus middleware collects metrics, Grafana reads from Prometheus, Sentry captures errors
- Responses flow back to Presentation → HTTP Response

c. Architectural patterns & principles:
- Layered Clean Architecture with strict inward dependencies
- Dependency Injection: DIContainer creates/injects all dependencies
- Repository & Unit of Work for data access and transactional boundaries
- Factory pattern inside DI for complex object creation
- SOLID principles in service and domain code

d. Key technologies & frameworks:
- FastAPI (presentation)
- SQLAlchemy + Alembic (PostgreSQL UoW & migrations)
- Motor or PyMongo (MongoDB)
- Redis-py (Redis cache)
- Ollama client (LLMProvider)
- Prometheus client + Grafana (monitoring)
- dependency-injector (DI)
- PyJWT (JWT auth)
- Sentry SDK (error tracking)

##### Final checklist for the principal software engineer
- Layer and component is labeled with its filesystem path (e.g., src/presentation/api/rest/v1).
- External dependencies and how traffic/data flows in and out.
- DIContainer as the orchestration point.
- Observability services (Prometheus → Grafana, Sentry) and security (JWT) as side-cars or external nodes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        REST["REST API Controllers"]:::presentation
        GraphQL["GraphQL API"]:::presentation
        Schemas["Pydantic Schemas"]:::presentation
    end

    %% Bootstrap & DI
    Bootstrap["DI Container & Bootstrap"]:::bootstrap

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        AnalyticsSvc["AnalyticsService"]:::application
        RequestSvc["RequestService"]:::application
        UserSvc["UserService"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        Entities["Entities"]:::domain
        Interfaces["Interfaces (Ports)"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        subgraph "PostgreSQL"
            UoW["UoW & Connection"]:::infra
            PGModels["Models"]:::infra
            PGRepos["Repositories"]:::infra
        end
        Mongo["MongoDB (Analytics)"]:::infra
        Redis["Redis Cache"]:::infra
        LLM["LLM Provider (Ollama)"]:::infra
        Security["Security (JWT/Auth)"]:::infra
        subgraph "Observability"
            Prom["Prometheus"]:::infra
            Graf["Grafana"]:::infra
            Sentry["Sentry"]:::infra
        end
    end

    %% Data Flows
    REST -->|"HTTP Request"| Bootstrap
    GraphQL -->|"HTTP Request"| Bootstrap
    Schemas --> Bootstrap

    Bootstrap -->|injects| AnalyticsSvc
    Bootstrap -->|injects| RequestSvc
    Bootstrap -->|injects| UserSvc

    AnalyticsSvc -->|uses| Entities
    AnalyticsSvc -->|calls| Interfaces
    RequestSvc -->|uses| Entities
    RequestSvc -->|calls| Interfaces
    UserSvc -->|uses| Entities
    UserSvc -->|calls| Interfaces

    Interfaces -->|implements| PGRepos
    Interfaces -->|implements| Mongo
    Interfaces -->|implements| LLM

    PGRepos -->|access| PGModels
    PGRepos -->|transactions| UoW
    UoW -->|connects| PostgreSQL[(PostgreSQL)]:::external
    Mongo -->|access| MongoDB[(MongoDB)]:::external
    Redis -->|cache| RequestSvc
    LLM -->|external call| OlLMService[(Ollama LLM)]:::external
    Security -->|auth| REST
    Security -->|auth| GraphQL

    REST -->|metrics| Prom
    GraphQL -->|metrics| Prom
    Prom -->|reads| Graf
    REST -->|errors| Sentry
    GraphQL -->|errors| Sentry
    AnalyticsSvc -->|errors| Sentry
    RequestSvc -->|errors| Sentry
    UserSvc -->|errors| Sentry

    %% Click Events
    click REST "https://github.com/temirlan-k/ollama-app/tree/main/src/presentation/api/rest/v1/"
    click GraphQL "https://github.com/temirlan-k/ollama-app/tree/main/src/presentation/api/graphql/"
    click Schemas "https://github.com/temirlan-k/ollama-app/tree/main/src/presentation/schemas/"
    click AnalyticsSvc "https://github.com/temirlan-k/ollama-app/blob/main/src/application/analytics_service.py"
    click RequestSvc "https://github.com/temirlan-k/ollama-app/blob/main/src/application/request_service.py"
    click UserSvc "https://github.com/temirlan-k/ollama-app/blob/main/src/application/user_service.py"
    click Entities "https://github.com/temirlan-k/ollama-app/tree/main/src/domain/entities/"
    click Interfaces "https://github.com/temirlan-k/ollama-app/tree/main/src/domain/interfaces/"
    click UoW "https://github.com/temirlan-k/ollama-app/blob/main/src/infra/db/postgres/uow.py"
    click PGModels "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/db/postgres/models/"
    click PGRepos "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/db/postgres/repositories/"
    click Mongo "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/db/mongo_db/"
    click Redis "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/db/cache/"
    click LLM "https://github.com/temirlan-k/ollama-app/blob/main/src/infra/llm_provider/ollama.py"
    click Security "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/security/auth/"
    click Prom "https://github.com/temirlan-k/ollama-app/tree/main/src/infra/prometheus/"
    click Graf "https://github.com/temirlan-k/ollama-app/blob/main/src/infra/grafana/fastapi-grafana.yml"
    click Sentry "https://github.com/temirlan-k/ollama-app/blob/main/src/infra/sentry/sentry.py"
    click Bootstrap "https://github.com/temirlan-k/ollama-app/blob/main/src/bootstrap/di_container.py"

    %% Styles
    classDef presentation fill:#D6EFFF,stroke:#0366d6,stroke-width:1px;
    classDef application fill:#D5F5E3,stroke:#27ae60,stroke-width:1px;
    classDef domain fill:#FCF3CF,stroke:#f1c40f,stroke-width:1px;
    classDef infra fill:#E8E8E8,stroke:#7f8c8d,stroke-width:1px;
    classDef bootstrap fill:#FADBD8,stroke:#c0392b,stroke-width:1px;
    classDef external fill:#FFFFFF,stroke:#cccccc,stroke-dasharray: 5 5;
```
