# osamahmada2024/neurina architecture

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

- Interactive diagram: https://gitdiagram.com/osamahmada2024/neurina
- Repository: https://github.com/osamahmada2024/neurina

## Overview

NeurinaXAI is a FastAPI image-translation and enhancement API with a separate agent-driven reference-selection capability. The primary workflow is an API request routed to image operations, which preprocess, translate or manage images, and use MongoDB and Cloudinary for persistence. Account authentication and public-reference synchronization are additional product stages. The graph includes the documented agent workflow, but its internal workflow wiring is not excerpted; those relationships are omitted rather than inferred.

Main entry points: [`src/main.py`](https://github.com/osamahmada2024/neurina/blob/main/src/main.py) (FastAPI app), [`src/controllers/image/controller.py`](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/controller.py) (Image controller), [`src/controllers/user_controller.py`](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/user_controller.py) (Account operations), [`src/controllers/image/base.py`](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/base.py) (Image state and storage helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounts"]
  node_app["FastAPI app<br/>[main.py]"]
  node_image_routes["Image routes<br/>[router.py]"]
  node_catalog["Image catalog API<br/>[catalog.py]"]
  node_user_routes["User routes<br/>[user_route.py]"]
  node_user_controller["Account operations<br/>[user_controller.py]"]
  node_auth["Authentication and email<br/>[auth_service.py]"]
end

subgraph group_images["Image workflows"]
  node_image_controller["Image controller<br/>[controller.py]"]
  node_preprocessing["Face preprocessing<br/>[preprocessing.py]"]
  node_translation["Style translation<br/>[translation.py]"]
  node_library["Image library<br/>[library.py]"]
  node_image_base["Image state and storage helpers<br/>[base.py]"]
end

subgraph group_agents["Agent orchestration"]
  node_agent_routes["Agent API<br/>[agent_routes.py]"]
  node_agent_workflow["Style-transfer workflow"]
  node_agent_stages["Agent stages"]
  node_agent_state["Agent state<br/>[agent_state.py]"]
  node_ollama["Ollama client<br/>[ollama_client.py]"]
end

subgraph group_runtime["Models and persistence"]
  node_mongo[("MongoDB<br/>[database.py]")]
  node_cloudinary["Cloudinary storage"]
  node_restoration["Face restoration"]
  node_model_preloader["Model preloader<br/>[model_preloader.py]"]
end

node_client(("API client"))
node_cloudinary_service["Cloudinary"]
node_ollama_service["Ollama service"]
node_user(("User"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts API"| node_image_routes
node_image_routes -->|"routes requests"| node_catalog
node_catalog -->|"calls image operations"| node_image_controller
node_image_controller -->|"inherits operations"| node_preprocessing
node_image_controller -->|"inherits operations"| node_translation
node_image_controller -->|"inherits operations"| node_library
node_image_controller -->|"inherits shared state"| node_image_base
node_image_base -->|"reads references"| node_mongo
node_image_base -->|"uses postprocessor"| node_restoration
node_app -->|"initializes database"| node_mongo
node_app -->|"loads models"| node_model_preloader
node_app -->|"initializes service"| node_cloudinary
node_cloudinary -.->|"uploads images"| node_cloudinary_service
node_user -.->|"uses account API"| node_user_routes
node_user_routes -.->|"dispatches account actions"| node_user_controller
node_user_controller -->|"reads and writes users"| node_mongo
node_user_controller -->|"verifies credentials"| node_auth
node_user_controller -->|"uploads profile pictures"| node_cloudinary
node_app -.->|"mounts API"| node_agent_routes
node_agent_routes -.->|"starts workflow"| node_agent_workflow
node_agent_workflow -.->|"dispatches stages"| node_agent_stages
node_agent_stages -->|"uses shared state"| node_agent_state
node_agent_stages -->|"requests generation"| node_ollama
node_ollama -->|"sends prompts"| node_ollama_service

click node_app "https://github.com/osamahmada2024/neurina/blob/main/src/main.py"
click node_image_routes "https://github.com/osamahmada2024/neurina/blob/main/src/routes/image/router.py"
click node_catalog "https://github.com/osamahmada2024/neurina/blob/main/src/routes/image/catalog.py"
click node_user_routes "https://github.com/osamahmada2024/neurina/blob/main/src/routes/user_route.py"
click node_user_controller "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/user_controller.py"
click node_auth "https://github.com/osamahmada2024/neurina/blob/main/src/services/auth_service.py"
click node_image_controller "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/controller.py"
click node_preprocessing "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/preprocessing.py"
click node_translation "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/translation.py"
click node_library "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/library.py"
click node_image_base "https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/base.py"
click node_agent_routes "https://github.com/osamahmada2024/neurina/blob/main/src/routes/agent_routes.py"
click node_agent_workflow "https://github.com/osamahmada2024/neurina/tree/main/src/orchestration/workflows"
click node_agent_stages "https://github.com/osamahmada2024/neurina/tree/main/src/orchestration/agents"
click node_agent_state "https://github.com/osamahmada2024/neurina/blob/main/src/schemes/agent_state.py"
click node_ollama "https://github.com/osamahmada2024/neurina/blob/main/src/helpers/AgentTools/ollama_client.py"
click node_mongo "https://github.com/osamahmada2024/neurina/blob/main/src/models/database/database.py"
click node_cloudinary "https://github.com/osamahmada2024/neurina/blob/main/src/services/cloudinary_service.py"
click node_restoration "https://github.com/osamahmada2024/neurina/blob/main/src/services/face_restoration_service.py"
click node_model_preloader "https://github.com/osamahmada2024/neurina/blob/main/src/services/model_preloader.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_app,node_image_routes,node_catalog,node_user_routes,node_user_controller,node_auth,node_client,node_user toneBlue
class node_image_controller,node_preprocessing,node_translation,node_library,node_image_base toneAmber
class node_agent_routes,node_agent_workflow,node_agent_stages,node_agent_state,node_ollama toneMint
class node_mongo,node_cloudinary,node_restoration,node_model_preloader toneRose
class node_cloudinary_service,node_ollama_service toneIndigo
```

## Components

### API and accounts

- [FastAPI app](https://github.com/osamahmada2024/neurina/blob/main/src/main.py): `src/main.py`
- [Image routes](https://github.com/osamahmada2024/neurina/blob/main/src/routes/image/router.py): `src/routes/image/router.py`
- [Image catalog API](https://github.com/osamahmada2024/neurina/blob/main/src/routes/image/catalog.py): `src/routes/image/catalog.py`
- [User routes](https://github.com/osamahmada2024/neurina/blob/main/src/routes/user_route.py): `src/routes/user_route.py`
- [Account operations](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/user_controller.py): `src/controllers/user_controller.py`
- [Authentication and email](https://github.com/osamahmada2024/neurina/blob/main/src/services/auth_service.py): `src/services/auth_service.py`

### Image workflows

- [Image controller](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/controller.py): `src/controllers/image/controller.py`
- [Face preprocessing](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/preprocessing.py): `src/controllers/image/preprocessing.py`
- [Style translation](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/translation.py): `src/controllers/image/translation.py`
- [Image library](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/library.py): `src/controllers/image/library.py`
- [Image state and storage helpers](https://github.com/osamahmada2024/neurina/blob/main/src/controllers/image/base.py): `src/controllers/image/base.py`

### Agent orchestration

- [Agent API](https://github.com/osamahmada2024/neurina/blob/main/src/routes/agent_routes.py): `src/routes/agent_routes.py`
- [Style-transfer workflow](https://github.com/osamahmada2024/neurina/tree/main/src/orchestration/workflows): `src/orchestration/workflows`
- [Agent stages](https://github.com/osamahmada2024/neurina/tree/main/src/orchestration/agents): `src/orchestration/agents`
- [Agent state](https://github.com/osamahmada2024/neurina/blob/main/src/schemes/agent_state.py): `src/schemes/agent_state.py`
- [Ollama client](https://github.com/osamahmada2024/neurina/blob/main/src/helpers/AgentTools/ollama_client.py): `src/helpers/AgentTools/ollama_client.py`

### Models and persistence

- [MongoDB](https://github.com/osamahmada2024/neurina/blob/main/src/models/database/database.py): `src/models/database/database.py`
- [Cloudinary storage](https://github.com/osamahmada2024/neurina/blob/main/src/services/cloudinary_service.py): `src/services/cloudinary_service.py`
- [Face restoration](https://github.com/osamahmada2024/neurina/blob/main/src/services/face_restoration_service.py): `src/services/face_restoration_service.py`
- [Model preloader](https://github.com/osamahmada2024/neurina/blob/main/src/services/model_preloader.py): `src/services/model_preloader.py`

### Other components

- **API client**
- **Cloudinary**
- **Ollama service**
- **User**

## Connections

- API client → FastAPI app: sends requests (evidence: `src/main.py`)
- FastAPI app → Image routes: mounts API (evidence: `src/main.py`)
- Image routes → Image catalog API: routes requests (evidence: `src/routes/image/router.py`)
- Image catalog API → Image controller: calls image operations (evidence: `src/routes/image/catalog.py`)
- Image controller → Face preprocessing: inherits operations (evidence: `src/controllers/image/controller.py`)
- Image controller → Style translation: inherits operations (evidence: `src/controllers/image/controller.py`)
- Image controller → Image library: inherits operations (evidence: `src/controllers/image/controller.py`)
- Image controller → Image state and storage helpers: inherits shared state (evidence: `src/controllers/image/controller.py`)
- Image state and storage helpers → MongoDB: reads references (evidence: `src/controllers/image/base.py`)
- Image state and storage helpers → Face restoration: uses postprocessor (evidence: `src/controllers/image/base.py`)
- FastAPI app → MongoDB: initializes database (evidence: `src/main.py`)
- FastAPI app → Model preloader: loads models (evidence: `src/main.py`)
- FastAPI app → Cloudinary storage: initializes service (evidence: `src/main.py`)
- Cloudinary storage → Cloudinary: uploads images
- User → User routes: uses account API
- User routes → Account operations: dispatches account actions
- Account operations → MongoDB: reads and writes users (evidence: `src/controllers/user_controller.py`)
- Account operations → Authentication and email: verifies credentials (evidence: `src/controllers/user_controller.py`)
- Account operations → Cloudinary storage: uploads profile pictures (evidence: `src/controllers/user_controller.py`)
- FastAPI app → Agent API: mounts API
- Agent API → Style-transfer workflow: starts workflow
- Style-transfer workflow → Agent stages: dispatches stages
- Agent stages → Agent state: uses shared state (evidence: `src/orchestration/agents/base_agent.py`)
- Agent stages → Ollama client: requests generation (evidence: `src/orchestration/agents/query_agent.py`)
- Ollama client → Ollama service: sends prompts (evidence: `src/helpers/AgentTools/ollama_client.py`)