# lander-hatsune/vecnote architecture

> Architecture diagram of the GitHub repository lander-hatsune/vecnote, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lander-hatsune/vecnote
- Repository: https://github.com/lander-hatsune/vecnote

## Overview

##### Main Components

a) Frontend Layer:
- Templates (Bulma-based UI)
- Static assets
- Document rendering components (Pandoc integration)

b) Backend Layer (Django):
- Document Management System
- Vector Embedding System
- GTD (Getting Things Done) System
- Search & Filter System

c) Database Layer:
- PostgreSQL with pgvector extension
- Document storage
- Vector embeddings storage

d) External Services:
- ZhipuAI API (for embeddings generation)
- Pandoc (for document conversion)

- [Frontend] → [Backend Services] → [Database & Storage]
- ↕
- [External Services]

##### Detailed Component Breakdown

Frontend Layer:
- Document views (create, edit, delete, restore)
- Todo management interface
- Search interface
- Document list/detail views
- Pin/Unpin functionality

Backend Services:
- Document Controller
- CRUD operations
- Document parsing (org/latex/typst)
- Vector Embedding Service
- Embedding generation
- Similarity search
- Todo Management Service
- Todo extraction
- Task scheduling
- Date management
- Search Service
- Vector-based search
- Filtering system

Database Layer:
- Document Store
- Vector Embeddings
- Todo Items
- Tags/Categories

##### Key Interactions to Highlight

- Document Flow:
- [User Input] → [Django View] → [Document Controller] → [Vector Embedding Service] → [Database]

- Search Flow:
- [Search Query] → [Search Service] → [Vector DB Query] → [Results]

- Todo Management Flow:
- [Document] → [Todo Extraction] → [Todo Storage] → [Todo View]

##### Important Architectural Notes

- Vector embedding pipeline
- Integration points with external services
- Document processing flow
- Demonstrate the GTD system integration

##### Technical Details

- Django MVT (Model-View-Template) pattern
- PostgreSQL with pgvector extension
- External API integrations
- Document conversion pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef database fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef api fill:#e74c3c,stroke:#c0392b,color:white

    %% Frontend Layer
    subgraph Frontend
        Templates["Templates & UI"]:::frontend
        DocUI["Document Management UI"]:::frontend
        GTDUI["GTD System UI"]:::frontend
        SearchUI["Search Interface"]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        Controllers["Backend Controllers"]:::backend
        Models["Data Models"]:::backend
        Forms["Form Processing"]:::backend
        Serializers["API Serialization"]:::backend
        URLRouter["URL Routing"]:::backend
        AdminInterface["Admin Interface"]:::backend

        subgraph Services
            DocService["Document Service"]:::backend
            VectorService["Vector Embedding Service"]:::backend
            TodoService["Todo Management Service"]:::backend
            SearchService["Search Service"]:::backend
        end
    end

    %% Database Layer
    subgraph Database
        PostgreSQL[("PostgreSQL + pgvector")]:::database
        DocStore[("Document Store")]:::database
        VectorStore[("Vector Embeddings")]:::database
        TodoStore[("Todo Items")]:::database
    end

    %% External Services
    subgraph External
        ZhipuAI["ZhipuAI API"]:::external
        Pandoc["Pandoc"]:::external
    end

    %% Relationships
    Templates --> Controllers
    DocUI --> Controllers
    GTDUI --> Controllers
    SearchUI --> Controllers

    Controllers --> DocService
    Controllers --> TodoService
    Controllers --> SearchService

    DocService --> VectorService
    VectorService --> ZhipuAI
    DocService --> Pandoc

    DocService --> DocStore
    VectorService --> VectorStore
    TodoService --> TodoStore
    SearchService --> VectorStore

    Models --> PostgreSQL
    Forms --> Controllers
    Serializers --> Controllers
    URLRouter --> Controllers
    AdminInterface --> Models

    %% Click Events
    click Templates "https://github.com/Lander-Hatsune/vecnote/blob/main/main/templates/base.html"
    click DocUI "https://github.com/Lander-Hatsune/vecnote/blob/main/main/templates/document_list.html"
    click GTDUI "https://github.com/Lander-Hatsune/vecnote/blob/main/main/templates/todos.html"
    click SearchUI "https://github.com/Lander-Hatsune/vecnote/blob/main/main/templates/search_form.html"
    click Controllers "https://github.com/Lander-Hatsune/vecnote/blob/main/main/views.py"
    click Models "https://github.com/Lander-Hatsune/vecnote/blob/main/main/models.py"
    click Forms "https://github.com/Lander-Hatsune/vecnote/blob/main/main/forms.py"
    click Serializers "https://github.com/Lander-Hatsune/vecnote/blob/main/main/serializers.py"
    click URLRouter "https://github.com/Lander-Hatsune/vecnote/blob/main/main/urls.py"
    click AdminInterface "https://github.com/Lander-Hatsune/vecnote/blob/main/main/admin.py"
```
