# nosia-ai/nosia architecture

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

- Interactive diagram: https://gitdiagram.com/nosia-ai/nosia
- Repository: https://github.com/nosia-ai/nosia

## Overview

##### Project Type and Purpose
- This is a full-stack Ruby on Rails application (“Nosia”) that provides a web UI (HTML + Stimulus/Turbo) and a JSON REST API under `/api/v1`.
- It integrates with an external AI inference service (Ollama), manages user data (documents, Q&As, chats), processes vector embeddings, and persists everything in a relational database.

##### High-Level Architecture Components
a. Client Layer
- Web browser/PWA
- Uses Turbo/Stimulus controllers, Tailwind CSS, service-worker (for offline)
- Interacts via HTTP(S) with Rails backend and WebSocket/ActionCable for real-time updates
b. Rails Application
- MVC structure
- Controllers: Web (`app/controllers/...`) and API (`app/controllers/api/v1/...`)
- Models: ActiveRecord for Users, Chats, Documents, Chunks, QnAs, API tokens, etc.
- Views: ERB templates (`app/views/...`), JSON builders for API
- Jobs: Background workers (`app/jobs/...`) for crawling, chunking, vectorizing, AI completions
- Services/Concerns: Authentication, vectorization, parsing, chunking logic
c. Data Stores
- PostgreSQL (configured in `config/database.yml`)
- ActiveStorage for file attachments
- Redis or other queue backend (Sidekiq/Kama l/Rails Queues via `config/queue.yml`)
d. Background Processing
- ActiveJob backed by Sidekiq or SolidQueue (configured in `config/solid_queue.yml`/`config/queue.yml`)
- Jobs send HTTP requests to the Ollama AI server, store embeddings/chunks back in DB
e. External AI Service
- Ollama inference server (local Docker container or remote, configured via `OLLAMA_BASE_URL`)
- Hosts LLMs (mistral, bespoke-minicheck, nomic-embed-text)
f. Infrastructure & Deployment
- Docker / Docker-Compose (`Dockerfile`, `docker-compose.yml`)
- Caddy (TLS reverse proxy) or Traefik (hooks in `.kamal/`)
- Devcontainer for local dev (`.devcontainer/*`)
- Scripts for start/stop/upgrade (`script/…`, `bin/dev`, `Procfile(.dev)`)

##### Relationships and Interactions
- Browser → Rails Web controllers (HTML/Turbo)
- Browser → Rails API controllers (JSON)
- Rails controllers → ActiveRecord → PostgreSQL
- Rails controllers → ActiveStorage → Disk or cloud storage
- Rails jobs → HTTP → Ollama → returns embeddings/completions → Rails persists results
- ActionCable WebSocket push: job status, chat updates
- Docker Compose orchestrates Rails + Ollama + Redis + Postgres
- Caddy/Traefik routes external HTTPS → Rails/ActionCable

##### Key Architectural Patterns
- MVC for request handling
- Layered services (parsing, chunking, vectorizing) factored into model concerns and jobs
- Background job processing for heavy AI and crawling tasks
- API versioning (`/api/v1`) separate from web UI
- PWA pattern (manifest.json, service-worker)
- Infrastructure as code (Docker, Kamal hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser/PWA"]:::ui
        Manifest["manifest.json"]:::ui
        ServiceWorker["service-worker.js"]:::ui
        Stimulus["Stimulus/Turbo Controllers"]:::ui
        Styles["Tailwind CSS"]:::ui
    end

    %% Web UI Layer
    subgraph "Web UI Layer"
        direction TB
        AccountsCtrl["AccountsController"]:::backend
        ChatsCtrl["ChatsController"]:::backend
        MessagesCtrl["MessagesController"]:::backend
        SessionsCtrl["SessionsController"]:::backend
        SettingsCtrl["SettingsController"]:::backend
        SourcesCtrl["Sources Controllers"]:::backend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIAppCtrl["API ApplicationController"]:::backend
        CompletionsCtrl["CompletionsController"]:::backend
        FilesCtrl["FilesController"]:::backend
        QnAsCtrl["QnAsController"]:::backend
        TextsCtrl["TextsController"]:::backend
        WebsitesCtrl["WebsitesController"]:::backend
    end

    %% Business Logic
    subgraph "Business Logic Layer"
        direction TB
        Models["Models"]:::backend
        ControllerConcerns["Controller Concerns"]:::backend
        ModelConcerns["Model Concerns"]:::backend
    end

    %% Background Jobs
    subgraph "Background Jobs Layer"
        direction TB
        AppJob["ApplicationJob"]:::backend
        CrawlJobs["Crawl Website Jobs"]:::backend
        IngestJobs["Ingestion Jobs"]:::backend
        AIJobs["AI Interaction Jobs"]:::backend
        MaintenanceJobs["Maintenance Jobs"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL"]:::data
        ActiveStorage["ActiveStorage"]:::data
        QueueBackend["Sidekiq/Queue"]:::data
    end

    %% External AI Service
    subgraph "External AI Service"
        Ollama["Ollama Inference Server"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure & Deployment"
        direction TB
        Docker["Docker & Docker-Compose"]:::infra
        DevContainer["Devcontainer"]:::infra
        Kamal["Kamal Hooks"]:::infra
        Proxy["Caddy/Traefik"]:::infra
        Procfiles["Procfile & Scripts"]:::infra
    end

    %% Connections
    Browser -->|HTTP/Turbo| AccountsCtrl
    Browser -->|HTTP/Turbo| ChatsCtrl
    Browser -->|HTTP/Turbo| MessagesCtrl
    Browser -->|HTTP/Turbo| SessionsCtrl
    Browser -->|HTTP/Turbo| SettingsCtrl
    Browser -->|HTTP/Turbo| SourcesCtrl
    Browser -->|Registers SW| ServiceWorker
    Browser -->|Loads Manifest| Manifest
    Browser -->|Loads CSS| Styles
    Browser -->|Bundles| Stimulus

    Browser -->|JSON/API| APIAppCtrl
    APIAppCtrl -->|routes to| CompletionsCtrl
    APIAppCtrl -->|routes to| FilesCtrl
    APIAppCtrl -->|routes to| QnAsCtrl
    APIAppCtrl -->|routes to| TextsCtrl
    APIAppCtrl -->|routes to| WebsitesCtrl

    AccountsCtrl -->|uses| Models
    ChatsCtrl -->|uses| Models
    MessagesCtrl -->|uses| Models
    SessionsCtrl -->|uses| Models
    SettingsCtrl -->|uses| Models
    SourcesCtrl -->|uses| Models

    CompletionsCtrl -->|uses| Models
    FilesCtrl -->|uses| Models
    QnAsCtrl -->|uses| Models
    TextsCtrl -->|uses| Models
    WebsitesCtrl -->|uses| Models

    Models -->|concerns| ControllerConcerns
    Models -->|concerns| ModelConcerns

    Models -->|read/write| Postgres
    Models -->|read/write| ActiveStorage

    Models -->|enqueue| QueueBackend

    QueueBackend -->|jobs| AppJob
    QueueBackend -->|jobs| CrawlJobs
    QueueBackend -->|jobs| IngestJobs
    QueueBackend -->|jobs| AIJobs
    QueueBackend -->|jobs| MaintenanceJobs

    AIJobs -->|HTTP| Ollama
    Ollama -->|embeddings/completions| Postgres

    Docker --> RailsMonolith["Rails Application"]:::backend
    Docker --> Ollama
    Docker --> QueueBackend
    Docker --> Postgres
    Proxy -->|routes HTTPS| RailsMonolith
    Proxy -->|routes WS| RailsMonolith

    DevContainer --> Docker
    Kamal --> Docker
    Procfiles --> Docker

    %% Click Events
    click Manifest "https://github.com/nosia-ai/nosia/blob/main/app/views/pwa/manifest.json.erb"
    click ServiceWorker "https://github.com/nosia-ai/nosia/blob/main/app/views/pwa/service-worker.js"
    click Stimulus "https://github.com/nosia-ai/nosia/tree/main/app/javascript/controllers/"
    click Styles "https://github.com/nosia-ai/nosia/blob/main/app/assets/stylesheets/application.tailwind.css"
    click AccountsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/accounts_controller.rb"
    click ChatsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/chats_controller.rb"
    click MessagesCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/messages_controller.rb"
    click SessionsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/sessions_controller.rb"
    click SettingsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/settings_controller.rb"
    click SourcesCtrl "https://github.com/nosia-ai/nosia/tree/main/app/controllers/sources/"
    click APIAppCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/application_controller.rb"
    click CompletionsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/completions_controller.rb"
    click FilesCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/files_controller.rb"
    click QnAsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/qnas_controller.rb"
    click TextsCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/texts_controller.rb"
    click WebsitesCtrl "https://github.com/nosia-ai/nosia/blob/main/app/controllers/api/v1/websites_controller.rb"
    click Models "https://github.com/nosia-ai/nosia/tree/main/app/models/"
    click ControllerConcerns "https://github.com/nosia-ai/nosia/blob/main/app/controllers/concerns/authentication.rb"
    click ModelConcerns "https://github.com/nosia-ai/nosia/tree/main/app/models/concerns/"
    click AppJob "https://github.com/nosia-ai/nosia/blob/main/app/jobs/application_job.rb"
    click CrawlJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/crawl_website_url_job.rb"
    click CrawlJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/crawl_website_urls_job.rb"
    click IngestJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/add_document_job.rb"
    click IngestJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/add_text_job.rb"
    click IngestJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/add_qna_job.rb"
    click AIJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/get_ai_response_job.rb"
    click MaintenanceJobs "https://github.com/nosia-ai/nosia/blob/main/app/jobs/upgrade_documents_job.rb"
    click Postgres "https://github.com/nosia-ai/nosia/blob/main/config/database.yml"
    click ActiveStorage "https://github.com/nosia-ai/nosia/blob/main/config/storage.yml"
    click QueueBackend "https://github.com/nosia-ai/nosia/blob/main/config/queue.yml"
    click Docker "https://github.com/nosia-ai/nosia/tree/main/Dockerfile"
    click Docker "https://github.com/nosia-ai/nosia/blob/main/docker-compose.yml"
    click DevContainer "https://github.com/nosia-ai/nosia/tree/main/.devcontainer/Dockerfile"
    click DevContainer "https://github.com/nosia-ai/nosia/blob/main/.devcontainer/compose.yaml"
    click DevContainer "https://github.com/nosia-ai/nosia/blob/main/.devcontainer/devcontainer.json"
    click Kamal "https://github.com/nosia-ai/nosia/tree/main/.kamal/hooks/"
    click Proxy "https://github.com/nosia-ai/nosia/tree/main/Caddyfile"
    click Procfiles "https://github.com/nosia-ai/nosia/tree/main/Procfile"
    click Procfiles "https://github.com/nosia-ai/nosia/blob/main/Procfile.dev"
    click Procfiles "https://github.com/nosia-ai/nosia/tree/main/bin/dev"
    click Procfiles "https://github.com/nosia-ai/nosia/tree/main/bin/docker-entrypoint"
    click Procfiles "https://github.com/nosia-ai/nosia/tree/main/script/"
    
    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FFE6,stroke:#28a745,color:#28a745
    classDef data fill:#FFE6CC,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F0E6FF,stroke:#800080,color:#800080
    classDef infra fill:#F0F0F0,stroke:#666666,color:#666666
```
