How nosia-ai/nosia works
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)