# tjmlabs/colivara architecture

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

- Interactive diagram: https://gitdiagram.com/tjmlabs/colivara
- Repository: https://github.com/tjmlabs/colivara

## Overview

##### Main Components
- API Server (Django-based):
- Located under the “web” directory.
- Contains two main submodules: “accounts” (e.g., user management, authentication) and “api” (document and collection management, search endpoints).
- Database:
- PostgreSQL with the pgVector extension for embedding storage.
- External Embeddings Service:
- Runs separately (ColiVarE repo) and provides GPU-powered generation of visual embeddings.
- Client SDKs:
- Python and TypeScript SDKs (colivara-py and colivara-ts) that interact with the REST API.
- Docker & CI/CD Infrastructure:
- Docker Compose files (“docker-compose.yml” and “docker-compose-prod.yml”) indicate container orchestration.
- GitHub workflows in the “.github/workflows” directory for testing, deployment, and release processes.
- Additional Supporting Elements:
- Documentation (in docs folder and external URLs).
- Configuration files (environment variables in .env.dev, example-nginx.conf).

##### Relationships and Interactions
- External Clients (via SDKs or direct REST calls) invoke endpoints on the API Server.
- The API Server processes requests such as document indexing and search.
- When a document is uploaded or indexed, the API Server forwards the file (or URL, base64 content) to the Embeddings Service, which generates embeddings.
- The API Server then stores and retrieves document information and embeddings from the Postgres database with pgVector.
- User management and authentication logic is handled within the “accounts” module.
- CI/CD pipelines (via GitHub workflows) manage automated testing, deployment, and release flows for the codebase.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separate concerns between API logic (views, controllers), business logic (models, migrations, management commands), and data persistence (Postgres).
- Microservices/Modular Integration: The external Embeddings Service serves as a loosely coupled microservice that can be swapped or updated independently.
- Containerization: Docker Compose is used to orchestrate the API server, database, and (in local development) possibly the Embeddings Service.
- Convention Over Configuration: As noted in the README, the API design uses opinionated defaults to ease development.
- Extensibility: The SDKs and REST API design permit clients to choose between using the provided SDKs or directly hitting the endpoints, which is crucial for integration flexibility.

##### Technologies
- Django framework (Python-based web framework) for the REST API.
- PostgreSQL with pgVector for vector storage.
- Docker for container orchestration.
- CI/CD workflows powered by GitHub Actions.
- External GPU-powered Embeddings Service using vision models.
- Python and TypeScript SDKs for client integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client SDKs/Users"]:::client
    B["Django API Server"]:::internal
    C["User Management & Authentication (accounts)"]:::internal
    D["Document & Collection Management (api)"]:::internal
    E["PostgreSQL (pgVector)"]:::database
    F["Embeddings Service (ColiVarE)"]:::external
    J["Configuration Management"]:::internal
    K["Docker Compose (dev)"]:::container
    L["Docker Compose (prod)"]:::container
    H["CI/CD Workflows"]:::ci
    I["Documentation & Examples"]:::docs

    A -->|"RESTrequests"| B
    B -->|"handles-auth"| C
    B -->|"handles-documents"| D
    D -->|"CRUD-embeddings"| E
    D -->|"embedding-request"| F
    J -->|"configures"| B
    K -->|"containerizes"| B
    L -->|"containerizes"| B
    H -->|"deploys-tests"| B

    %% Click Events
    click B "https://github.com/tjmlabs/colivara/tree/main/web/"
    click C "https://github.com/tjmlabs/colivara/tree/main/web/accounts"
    click D "https://github.com/tjmlabs/colivara/tree/main/web/api"
    click E "https://github.com/tjmlabs/colivara/blob/main/web/api/migrations/0001_enable_pgvector.py"
    click F "https://github.com/tjmlabs/colivara/blob/main/web/api/management/commands/update_embeddings.py"
    click J "https://github.com/tjmlabs/colivara/tree/main/web/config"
    click K "https://github.com/tjmlabs/colivara/blob/main/docker-compose.yml"
    click L "https://github.com/tjmlabs/colivara/blob/main/docker-compose-prod.yml"
    click H "https://github.com/tjmlabs/colivara/tree/main/.github/workflows"
    click I "https://github.com/tjmlabs/colivara/tree/main/docs"

    %% Styles
    classDef internal fill:#d4f0fc,stroke:#1f78b4,stroke-width:2px
    classDef external fill:#ffe6e6,stroke:#e60000,stroke-width:2px
    classDef client fill:#e6ffe6,stroke:#009933,stroke-width:2px
    classDef database fill:#fff0b3,stroke:#e68a00,stroke-width:2px
    classDef container fill:#f0e6ff,stroke:#9933cc,stroke-width:2px
    classDef ci fill:#f9e79f,stroke:#f39c12,stroke-width:2px
    classDef docs fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
```
