# doclin-dev/doclin architecture

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

- Interactive diagram: https://gitdiagram.com/doclin-dev/doclin
- Repository: https://github.com/doclin-dev/doclin

## Overview

##### Main Components
- Backend API – Located in the “api” directory, this is the main TypeScript/Node.js service. It handles REST endpoints (see controllers, routes, middlewares), interacts with a PostgreSQL database (entities, repositories and data source configuration), and integrates with external services such as GitHub (OAuth), SendGrid (email notifications), and OpenAI via an API key (to support the copilot features).
- Python Embedding Service – Found in the “python-api” directory, this separate service (using Python) is likely responsible for tasks like processing or generating code embeddings for advanced features.
- Shared Module – The “shared” directory contains common services, API interfaces, enums, and type definitions that are used across multiple parts of the system to ensure consistency between client and server interactions.
- Client Extensions – There are multiple IDE integrations:
- VS Code Extension – In the “extension” directory, which includes not only the integration logic (communication with the API, caching, and state management) but also webview components (Svelte-based) to render UI inside the editor.
- IntelliJ Plugin – Located in the “doclin-intellij” directory, built using Kotlin and Gradle, serving similar integration purposes for IntelliJ users.
- Web Application – The “webapp” folder represents a standalone front-end client, built likely with Svelte (judging by the .svelte files) along with Tailwind and Vite configuration, which allows users to access Doclin via a browser.
- External Dependencies – These include:
- PostgreSQL for persistence (as referenced in the API configuration).
- Third-party services (GitHub for authentication, SendGrid for email notifications, and OpenAI for copilot functionality).

##### Relationships and Interactions
- Client devices (VS Code, IntelliJ, and web browser) send requests to the Backend API.
- The API server orchestrates requests by routing them through controllers and middleware, then accesses the persistence layer (repositories/entities) in PostgreSQL.
- The Shared module is used across both the backend and client extensions for type safety and consistency in API calls.
- The Python API acts as a microservice (or auxiliary service) for embedding tasks, which may be invoked by the main API or directly by client services.
- External integrations (GitHub, SendGrid, OpenAI) are invoked by the backend to support features like login authentication, email notifications, and intelligent code suggestions.
- Docker Compose (docker-compose.yml) is used to orchestrate the containerized deployment of these services.

##### Important Architectural Patterns & Principles
- Separation of Concerns: The project is segmented into clear domains – backend services, different client integrations (IDE extensions and webapp), and shared business logic.
- Microservices / Modular Service Design: The existence of both the Node.js API and the Python API indicates a modular design for handling distinct responsibilities.
- MVC and Repository Patterns: Within the API, controllers, middleware, entities, and repositories reflect a structured pattern that separates routing, business logic, database interactions, and utility functions.
- Client-Server Communication: All clients interact with the backend API using well-defined endpoints and shared DTOs, ensuring reusable and consistent communication protocols.
- Containerization: The Dockerfiles and docker-compose.yml are used to ensure consistency in deployment across environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        VSCode["VS Code Extension\n(extension)"]:::client
        IntelliJ["IntelliJ Plugin\n(doclin-intellij)"]:::client
        WebApp["Web Application\n(webapp)"]:::client
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        API["API Server\n(api/src/controllers, api/src/database, etc.)"]:::backend
        Python["Python Embedding Service\n(python-api/embedding.py)"]:::backend
    end

    %% Shared and External Dependencies Layer
    subgraph "Shared & External"
        Shared["Shared Module\n(shared/apiService, shared/types, etc.)"]:::shared
        External["External Services\n(GitHub,SendGrid,OpenAI)"]:::external
    end

    %% Database Layer
    Database["Database\n(PostgreSQL)"]:::database

    %% Data flows from Clients to API
    VSCode -->|"calls"| API
    IntelliJ -->|"calls"| API
    WebApp -->|"calls"| API

    %% API interactions with backend and external services
    API -->|"invokes"| Python
    API -->|"uses"| Shared
    API -->|"communicates"| External
    API -->|"queries"| Database

    %% Clients also leverage Shared Module for consistency
    VSCode ---|"utilizes"| Shared
    IntelliJ ---|"utilizes"| Shared
    WebApp ---|"utilizes"| Shared

    %% Styling for better visual separation
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef shared fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef database fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events for Components
    click VSCode "https://github.com/doclin-dev/doclin/tree/main/extension"
    click IntelliJ "https://github.com/doclin-dev/doclin/tree/main/doclin-intellij"
    click WebApp "https://github.com/doclin-dev/doclin/tree/main/webapp"
    click API "https://github.com/doclin-dev/doclin/tree/main/api"
    click Python "https://github.com/doclin-dev/doclin/blob/main/python-api/embedding.py"
    click Shared "https://github.com/doclin-dev/doclin/tree/main/shared"
```
