# stebis-dev/doci architecture

> Architecture diagram of the GitHub repository stebis-dev/doci, 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/stebis-dev/doci
- Repository: https://github.com/stebis-dev/doci

## Overview

##### Project Type and Purpose
- Type: Full-stack desktop application with optional cloud services, packaged via Electron and orchestrated in an Nx monorepo.
- Purpose: A cross-platform code-documentation tool (“Doci”) that parses code (via Tree-sitter), displays it in an Angular UI, imports from GitHub, and offloads heavy documentation generation to Azure Functions.

##### File Structure
- Top-level “apps/” contains three applications:
– angular-client (the Angular renderer UI)
– electron (the Electron main process & IPC handlers)
– renderer-e2e (Cypress tests for the UI)
- “azure/” holds serverless functions:
– githubTokenExchange.ts (OAuth token exchange)
– codeDocumentation.ts (server-side doc generation)
- “libs/shared” exposes constants and models used by both Electron and Angular.
- Services in angular-client/src/app/service cover: file system, GitHub, Tree-sitter parsing, description generation, query extraction.

##### README for Additional Insights
- Confirms: Nx-based monorepo, Angular + Electron dev flow, Azure Functions packaging, CI/CD workflows.
- Heavy use of Nx workflows to build, serve, and package each app.

##### Main Components & Their Interactions
a. Angular Renderer (apps/angular-client)
– UI components, services, and assets (Tree-sitter WASM).
– Communicates with Electron main via IPC (electron.service).
– Makes HTTP calls to Azure Functions for code documentation and token exchange.
b. Electron Main Process (apps/electron)
– Exposes IPC endpoints (api/github-auth.api.ts, main.preload.ts).
– Handles local file-system access (fileSystem.service), GitHub import (github-importer.handler), environment utilities.
– Packages the Angular bundle into a desktop app.
c. Azure Functions (azure/src/functions)
– githubTokenExchange: Exchanges OAuth codes with GitHub.
– codeDocumentation: Processes code ASTs (potentially using shared parser strategies) and returns documentation output.
d. External Services
– GitHub REST API for repo metadata and OAuth.
– (Optional) Additional external services if integrated.
e. Shared Libraries (libs/shared)
– Types, models, and constants reused by both front end and back end for type safety and consistency.

##### Architectural Patterns & Design Principles
- Monorepo with Nx: promotes modularity, shared code, and unified build/test scripts.
- Separation of Concerns:
– Renderer (View + client-side logic)
– Main (Platform glue, native FS, IPC, packaging)
– Serverless (Heavy compute / secure token exchange)
- IPC boundary: Clearly define channels for FS, GitHub, config, and events.
- Service abstraction: Angular services encapsulate data-fetching, parsing, theme management.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Angular Renderer" 
        direction TB
        UI["Core UI Components"]:::frontend
        Routing["Routing & Config"]:::frontend
        Services["Angular Services"]:::frontend
        WASM["Tree-sitter WASM Assets"]:::frontend
    end

    subgraph "Electron Main Process"
        direction TB
        MainEntry["Entry Point (main.ts)"]:::backend
        AppBootstrap["App Bootstrap (app.ts)"]:::backend
        IPC["IPC API Endpoints"]:::backend
        Handlers["Handlers & Importers"]:::backend
        Events["Event Definitions"]:::backend
        Utils["Env Utils & Constants"]:::backend
    end

    subgraph "Azure Functions"
        direction TB
        TokenExchange["githubTokenExchange"]:::serverless
        CodeDocs["codeDocumentation"]:::serverless
    end

    ExternalGitHub["GitHub REST API"]:::external
    FileSystem["Local File System"]:::external

    subgraph "Nx Workspace"
        direction TB
        SharedLibs["Shared Libs (libs/shared)"]:::shared
        Constants["Constants"]:::shared
        Models["Models/Types"]:::shared
    end

    subgraph "CI/CD Workflows"
        direction TB
        CDAngular["CD-angular.yml"]:::external
        CDAzure["CD-azure-function.yml"]:::external
        CIElectron["CI-electron.yml"]:::external
        CIMonorepo["ci.yml"]:::external
    end

    %% Connections
    UI -->|"uses"| Services
    UI -->|"loads WASM"| WASM
    Services -->|"IPC"| IPC
    IPC -->|"serves renderer"| MainEntry
    MainEntry -->|"bootstrap"| AppBootstrap
    AppBootstrap -->|"exposes"| IPC
    AppBootstrap -->|"handles"| Handlers
    Handlers -->|"accesses"| FileSystem
    MainEntry -->|"calls REST"| ExternalGitHub
    AppBootstrap -->|"HTTP"| TokenExchange
    AppBootstrap -->|"HTTP"| CodeDocs
    Services -->|"HTTP"| TokenExchange
    Services -->|"HTTP"| CodeDocs
    MainEntry -->|"uses"| Utils
    MainEntry -->|"emits"| Events

    SharedLibs --> UI
    SharedLibs --> MainEntry
    SharedLibs --> TokenExchange
    SharedLibs --> CodeDocs

    ExternalGitHub ---|"OAuth/REST"| Services
    ExternalGitHub ---|"REST"| MainEntry
    FileSystem ---|"FS API"| AppBootstrap

    CDAngular --> UI
    CIElectron --> AppBootstrap
    CDAzure --> TokenExchange
    CIMonorepo --> SharedLibs

    %% Click Events
    click UI "https://github.com/stebis-dev/doci/tree/main/apps/angular-client/src/app/components"
    click Routing "https://github.com/stebis-dev/doci/blob/main/apps/angular-client/src/app/app.routes.ts"
    click Routing "https://github.com/stebis-dev/doci/blob/main/apps/angular-client/src/app/app.config.ts"
    click Services "https://github.com/stebis-dev/doci/tree/main/apps/angular-client/src/app/service"
    click WASM "https://github.com/stebis-dev/doci/tree/main/apps/angular-client/src/assets/tree-sitter"

    click MainEntry "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/main.ts"
    click AppBootstrap "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/app.ts"
    click IPC "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/api/github-auth.api.ts"
    click IPC "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/api/main.preload.ts"
    click Handlers "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/handler/projectImporter.handler.ts"
    click Events "https://github.com/stebis-dev/doci/tree/main/apps/electron/src/app/events"
    click Utils "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/utils/env.util.ts"
    click Utils "https://github.com/stebis-dev/doci/blob/main/apps/electron/src/app/constants.ts"

    click TokenExchange "https://github.com/stebis-dev/doci/blob/main/azure/src/functions/githubTokenExchange.ts"
    click CodeDocs "https://github.com/stebis-dev/doci/blob/main/azure/src/functions/codeDocumentation.ts"

    click SharedLibs "https://github.com/stebis-dev/doci/blob/main/libs/shared/index.ts"
    click Constants "https://github.com/stebis-dev/doci/tree/main/libs/shared/constants"
    click Models "https://github.com/stebis-dev/doci/tree/main/libs/shared/models"

    click CDAngular "https://github.com/stebis-dev/doci/blob/main/.github/workflows/CD-angular.yml"
    click CDAzure "https://github.com/stebis-dev/doci/blob/main/.github/workflows/CD-azure-function.yml"
    click CIElectron "https://github.com/stebis-dev/doci/blob/main/.github/workflows/CI-electron.yml"
    click CIMonorepo "https://github.com/stebis-dev/doci/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0366d6
    classDef backend fill:#d9ead3,stroke:#38761d
    classDef serverless fill:#f9cb9c,stroke:#b45f06
    classDef external fill:#d9d2e9,stroke:#5f4b8b
    classDef shared fill:#ead1dc,stroke:#a64d79
```
