# lit-24-25/github-issues architecture

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

- Interactive diagram: https://gitdiagram.com/lit-24-25/github-issues
- Repository: https://github.com/lit-24-25/github-issues

## Overview

##### Project type and purpose
- This is a full-stack Django web application (“GitHelp”) that provides technical support for GitHub repositories.
- It uses GitHub Issues as its knowledge base and leverages external LLM/embedding services (OpenRouter, GigaChat) plus an internal retrieval pipeline to answer users’ questions.

##### File structure
- Top-level Django project:
- issues_project/          ← Django project configuration (settings, URLs, ASGI/WSGI)
- manage.py                ← Django CLI entry point
- Django apps:
- question_app/            ← Handles question submission, context building, HTTP views, templates, serializers, URLs, management command (train_model)
- conversation/            ← Manages conversation history models, views, admin interface
- Pure‐Python business logic module:
- business_logic/          ← Implements chunking, vector store (Chroma), embedding/model wrappers, retrieval, training orchestration
- Tests and cassettes:
- tests/                   ← Unit/integration tests, VCR cassettes for GitHub API mocks, markdown issue fixtures
- Config/deploy:
- .github/workflows/main.yml ← CI pipeline
- requirements.txt, setup.py, pytest.ini

##### README for additional insights
- Describes external dependencies: GitHub token, OpenRouter API key, GigaChat API key
- Outlines the training step (manage.py train_model) to ingest repository issues into the embedding store
- Outlines the server startup and usage flow

##### Main components and their interactions
a. Frontend (Browser)
- Users access a Django‐rendered HTML form or conversation UI (templates/question_app/*.html)
b. Django Web Server
- question_app.views: handles question submissions, invokes business_logic.retrieve()
- conversation.views: serves conversation history, admin interface
c. Business Logic Layer (business_logic/)
- train.py: orchestration for building the embedding store
- chunks.py: splits issue text into retrievable chunks
- mychroma.py: vector store interface (ChromaDB)
- mymodel.py: abstraction over OpenRouter/GigaChat API calls
- retrieve.py: retrieves top‐k chunks and assembles prompts
d. Database
- Django ORM models: question_app.models (questions, contexts), conversation.models (messages, threads)
e. External Services
- GitHub REST API: fetch raw issue data during training & retrieval
- OpenRouter API: language model inference for answer generation
- GigaChat API: embedding generation (and possibly chat)
f. CI/CD Pipeline
- GitHub Actions: runs tests via pytest

##### Relationships & data flow
1. User → HTTP POST /ask → question_app.views
2. question_app → business_logic.retrieve()
3. retrieve():
- fetches embeddings from ChromaDB
- if cache miss, may call GitHub API
- calls model APIs for answer
4. business_logic returns answer → question_app stores question/answer in DB
5. question_app returns HTTP response → User
6. Admin or conversation UI → conversation.models → DB → views → User

##### Architectural patterns and principles
- Layered architecture:
- Presentation (templates, serializers, views)
- Application logic (Django apps)
- Domain/Business logic (vector retrieval, model wrappers)
- Infrastructure (DB, external APIs)
- Single-monolith deployment (no microservices), with clear separation of concerns via Python packages and Django apps
- Command-based orchestration (train_model) for offline processing
- Use of Django’s management command and ORM to persist conversational state

##### Final checklist
- [ ] Browser/UI
- [ ] Django Web Server subdivided by app
- [ ] Business Logic modules
- [ ] Database (ORM models)
- [ ] External APIs (GitHub, OpenRouter, GigaChat)
- [ ] Management command path (train_model)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    UI["Browser UI<br/>(Django Templates)"]:::frontend
    click UI "https://github.com/lit-24-25/github-issues/blob/main/question_app/templates/question_app/question.html"

    %% Django Web Server
    subgraph "Django Web Server" 
        direction TB
        QA_Views["Question App Views"]:::backend
        click QA_Views "https://github.com/lit-24-25/github-issues/blob/main/question_app/views.py"
        QA_URLs["Question App URLs"]:::backend
        click QA_URLs "https://github.com/lit-24-25/github-issues/blob/main/question_app/urls.py"
        QA_Models["Question App Models"]:::backend
        click QA_Models "https://github.com/lit-24-25/github-issues/blob/main/question_app/models.py"
        QA_Serializers["Question App Serializers"]:::backend
        click QA_Serializers "https://github.com/lit-24-25/github-issues/blob/main/question_app/serializers.py"
        QA_Router["Question App Router"]:::backend
        click QA_Router "https://github.com/lit-24-25/github-issues/blob/main/question_app/router.py"
        QA_Admin["Question App Admin"]:::backend
        click QA_Admin "https://github.com/lit-24-25/github-issues/blob/main/question_app/admin.py"

        Conv_Views["Conversation Views"]:::backend
        click Conv_Views "https://github.com/lit-24-25/github-issues/blob/main/conversation/views.py"
        Conv_Models["Conversation Models"]:::backend
        click Conv_Models "https://github.com/lit-24-25/github-issues/blob/main/conversation/models.py"
        Conv_Admin["Conversation Admin"]:::backend
        click Conv_Admin "https://github.com/lit-24-25/github-issues/blob/main/conversation/admin.py"
        Conv_Config["Conversation Config"]:::backend
        click Conv_Config "https://github.com/lit-24-25/github-issues/blob/main/conversation/apps.py"

        TrainCmd["Management Command<br/>(train_model)"]:::backend
        click TrainCmd "https://github.com/lit-24-25/github-issues/blob/main/question_app/management/commands/train_model.py"
    end

    %% Business Logic Layer
    subgraph "Business Logic Package" 
        direction TB
        Chunks["Chunking Module"]:::biz
        click Chunks "https://github.com/lit-24-25/github-issues/blob/main/business_logic/chunks.py"
        VectorStore["Chroma Vector Store"]:::biz
        click VectorStore "https://github.com/lit-24-25/github-issues/blob/main/business_logic/mychroma.py"
        ModelAPI["Model API Wrappers"]:::biz
        click ModelAPI "https://github.com/lit-24-25/github-issues/blob/main/business_logic/mymodel.py"
        Retrieve["Retrieval Logic"]:::biz
        click Retrieve "https://github.com/lit-24-25/github-issues/blob/main/business_logic/retrieve.py"
        TrainOrch["Training Orchestration"]:::biz
        click TrainOrch "https://github.com/lit-24-25/github-issues/blob/main/business_logic/train.py"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub Issues API"]:::external
        OpenRouterAPI["OpenRouter API"]:::external
        GigaChatAPI["GigaChat API"]:::external
    end

    %% Database
    DB[(Django ORM / Models)]:::database

    %% Flows
    UI -->|"POST /ask"| QA_Views
    QA_Views -->|"calls retrieve()"| Retrieve
    Retrieve -->|"query embeddings"| VectorStore
    VectorStore -->|"cache miss?"| GitHubAPI
    Retrieve -->|"generate prompt"| ModelAPI
    ModelAPI -->|"LLM inference"| OpenRouterAPI
    ModelAPI -->|"embeddings"| GigaChatAPI
    Retrieve -->|"return answer"| QA_Views
    QA_Views -->|"save Q&A"| DB
    QA_Views -->|"HTTP Response"| UI

    UI -->|"admin/conversation"| Conv_Views
    Conv_Views -->|"loads history"| DB
    Conv_Views -->|"renders UI"| UI

    TrainCmd -->|"invoke TrainOrch"| TrainOrch
    TrainOrch -->|"split issues"| Chunks
    TrainOrch -->|"store vectors"| VectorStore
    TrainOrch -->|"fetch issues"| GitHubAPI

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B99,color:#000;
    classDef backend fill:#E0F8E0,stroke:#2E7D32,color:#000;
    classDef biz fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef external fill:#E1BEE7,stroke:#6A1B9A,color:#000;
    classDef database fill:#E0E0E0,stroke:#616161,color:#000;
```
