# gbrian/codx-junior architecture

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

- Interactive diagram: https://gitdiagram.com/gbrian/codx-junior
- Repository: https://github.com/gbrian/codx-junior

## Overview

##### Project type and purpose
- codx-junior is a full-stack, AI-powered project management platform for open-source software.
- It automates tasks, code generation and review, Kanban boards, knowledge retrieval (RAG), LLM orchestration, and provides a web client and programmable API.

##### File structure
- Top-level modules:
- api (Python FastAPI + Socket.IO backend, project watcher, background jobs, knowledge engine)
- client (Vue.js/Vite front-end, HTTP + WebSocket integration)
- llm-factory (Python microservice for LLM model management and RAG, exposes OpenAI-compatible endpoints)
- browser (Python scripts / Jupyter for embedded browsing, code-server / noVNC support)
- web (static/demo Vue.js site)
- code-server (IDE container)
- Orchestration & deployment: Dockerfile, docker-compose.dev.yaml, supervisor configs under scripts/supervisor.*.conf
- Data stores: file-based SQLite (codx.db.json), Milvus vector store for knowledge retrieval
- External dependencies: OpenAI, Anthropic, Mistral, Ollama LLM providers; Socket.IO client/server; Docker containers

##### README for additional insights
- README emphasizes four “apps”: client, api, llm-factory, docker
- Describes AI flows driven by “profiles” and “tasks” stored in .codx directories
- Shows use cases: dashboard, Kanban, code generation, Docker integration, RAG knowledge

a. Main components
- Front-end (client Vue.js app)
- API service (FastAPI + Socket.IO)
- LLM-Factory service (model registry, authentication, proxy)
- Knowledge subsystem (RAG pipelines and Milvus vector DB)
- Background workers (project watcher, mention manager, profiling)
- Supervisor / orchestrator (supervisord + Docker Compose)
- Data stores: SQL (SQLite) and Vector store (Milvus)
- External providers: OpenAI, Anthropic, Mistral, Ollama
b. Relationships & interactions
- Client ↔ API over HTTPS and WebSocket (Socket.IO)
- API → LLM-Factory REST endpoints for on-demand model inference or training calls
- API & LLM-Factory → External LLM providers (OpenAI, etc.)
- API background tasks → Knowledge subsystem for ingestion, indexing → Milvus
- Client & API → SQLite for user, project, task metadata
- Supervisor orchestrates all containers/services at startup
c. Architectural patterns & principles
- Microservices: each module runs in its own container or process
- Event-driven: background tasks and watchers react to file changes and triggers
- “Adapter” pattern for LLM providers (llmfactory wraps OpenAI, Anthropic, Mistral)
- RAG pipeline: document splitter → embeddings → vector store → similarity search
d. Technologies / frameworks
- Python FastAPI, Socket.IO, asyncio
- Vue.js, Vite, Vuex store, Vue Router
- Docker Compose, supervisord
- Milvus (vector DB)
- External APIs: OpenAI, Anthropic, Mistral, Ollama

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Network"
        direction TB

        subgraph "Client Layer"
            direction TB
            Client["Front-end (Vue.js)"]:::frontend
        end

        subgraph "API Service Layer"
            direction TB
            API["API Service (FastAPI + Socket.IO)"]:::backend

            subgraph "Internal Modules"
                direction TB
                PW["Project Watcher"]:::backend
                BG["Background Jobs"]:::backend
                MM["Mention Manager"]:::backend
                TM["Task Manager"]:::backend
                Profiling["Profiler"]:::backend

                subgraph "Knowledge Subsystem"
                    direction TB
                    Splitter["Splitters & Loaders"]:::backend
                    KnowledgeCore["Knowledge Core"]:::backend
                    MilvusAdapter["Milvus Adapter"]:::backend
                    PrePrompts["PrePrompts & Settings"]:::backend
                end

                subgraph "AI Adapters"
                    direction TB
                    OpenAIAdapter["OpenAI Adapter"]:::external
                    AnthropicAdapter["Anthropic Adapter"]:::external
                    MistralAdapter["Mistral Adapter"]:::external
                    LLMFactoryBridge["LLMFactory Bridge"]:::external
                end
            end
        end

        subgraph "LLM-Factory Service"
            direction TB
            LLMF["LLM-Factory (Model Registry & Proxy)"]:::backend
            ModelDef["Model Definitions"]:::backend
            Admin["Auth & Admin"]:::backend
            LLMConfig["Configuration & Tasks"]:::backend
        end

        Browser["Browser Integration (Scripts & Jupyter)"]:::backend
        CodeServer["Code-Server IDE"]:::backend
        WebDemo["Web Demo Site (Vue.js)"]:::frontend
    end

    subgraph "Data Stores"
        direction TB
        SQLite["SQLite DB"]:::datastore
        Milvus["Milvus Vector Store"]:::datastore
    end

    subgraph "External LLM Providers"
        direction TB
        EOpenAI["OpenAI"]:::external
        EAnthropic["Anthropic"]:::external
        EMistral["Mistral"]:::external
        EOllama["Ollama"]:::external
    end

    Client -->|HTTP/WS| API
    API -->|REST| LLMF
    API --> PW
    API --> BG
    API --> MM
    API --> TM
    API --> Profiling

    API --> Splitter
    Splitter --> KnowledgeCore
    KnowledgeCore --> MilvusAdapter
    MilvusAdapter --> Milvus
    KnowledgeCore --> PrePrompts

    API --> OpenAIAdapter
    API --> AnthropicAdapter
    API --> MistralAdapter
    API --> LLMFactoryBridge

    LLMF --> EOpenAI
    LLMF --> EAnthropic
    LLMF --> EMistral
    LLMF --> EOllama

    API --> SQLite

    classDef frontend fill:#D0E8FF,stroke:#3399FF,color:#000
    classDef backend fill:#E6F4EA,stroke:#2E8B57,color:#000
    classDef datastore fill:#FFE5B4,stroke:#FF8C00,color:#000
    classDef external fill:#F3E5F5,stroke:#800080,color:#000

    click Client "https://github.com/gbrian/codx-junior/tree/main/client/"
    click API "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/app.py"
    click PW "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/project_watcher.py"
    click BG "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/background.py"
    click MM "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/mention_manager.py"
    click TM "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/task_manager.py"
    click Profiling "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/profiling/profiler.py"
    click Splitter "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/knowledge/knowledge_splitter.py"
    click KnowledgeCore "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/knowledge/knowledge.py"
    click MilvusAdapter "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/knowledge/knowledge_milvus.py"
    click PrePrompts "https://github.com/gbrian/codx-junior/tree/main/api/codx/junior/knowledge/prepromts/"
    click OpenAIAdapter "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/ai/openai_ai.py"
    click AnthropicAdapter "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/ai/anthropic.py"
    click MistralAdapter "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/ai/mistral_ai.py"
    click LLMFactoryBridge "https://github.com/gbrian/codx-junior/blob/main/api/codx/junior/ai/llmfactory.py"
    click LLMF "https://github.com/gbrian/codx-junior/blob/main/llm-factory/main.py"
    click ModelDef "https://github.com/gbrian/codx-junior/blob/main/llm-factory/model.py"
    click Admin "https://github.com/gbrian/codx-junior/blob/main/llm-factory/admin/user.py"
    click LLMConfig "https://github.com/gbrian/codx-junior/tree/main/llm-factory/.codx/"
    click Browser "https://github.com/gbrian/codx-junior/tree/main/browser/"
    click CodeServer "https://github.com/gbrian/codx-junior/tree/main/code-server/"
    click WebDemo "https://github.com/gbrian/codx-junior/tree/main/web/"
    click SQLite "https://github.com/gbrian/codx-junior/blob/main/.codx/usrlocalcodxjuniorcodx.db.json"
```
