# teamial/devtrack architecture

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

- Interactive diagram: https://gitdiagram.com/teamial/devtrack
- Repository: https://github.com/teamial/devtrack

## Overview

##### Main Components
- VS Code Extension Host: The core of the extension as indicated in src/extension.ts and supporting files like vsc-extension-quickstart.md.
- UI Components: Located in src/components (for example, CodingStatsDashboard.tsx and card.tsx inside the “ui” folder), which serve to display information in the editor (like status bar updates and dashboards).
- Services Layer: A collection of modules in src/services that encapsulate individual responsibilities:
- changeAnalyzer.ts: Monitors file changes.
- gitService.ts: Handles local Git operations.
- githubService.ts: Manages GitHub interactions (authentication, commit push, repository management).
- projectContext.ts: Captures contextual information about the current workspace/project.
- scheduler.ts: Manages commit frequency and scheduling periodic tasks.
- statisticsProvider.ts & statisticsView.ts: Compute and display coding statistics.
- statusBarManager.ts: Updates the VS Code status bar with tracking status and last commit time.
- summaryGenerator.ts: Builds commit summaries from the tracked data.
- tracker.ts: Orchestrates the tracking process.
- websiteGenerator.ts: (Optional) Generates web-based views or reports of coding progress.
- External Dependencies:
- Git: Required for tracking local code changes.
- GitHub: For repository management (the automatic “code-tracking” repository).
- VS Code’s secure authentication and status bar APIs.

##### Relationships and Interactions
- The Extension Host (src/extension.ts) serves as the entry point that initializes the various services when the extension is activated.
- UI Components receive data from services (for example, the CodingStatsDashboard displaying statistics from statisticsProvider) and update status information via statusBarManager.
- The services are interconnected:
- changeAnalyzer detects file changes and informs scheduler.
- scheduler triggers tracker which in turn makes use of gitService and githubService to commit updates.
- summaryGenerator creates commit messages based on analysis from statistics-related services.
- projectContext provides the current working environment context to all tracking and logging operations.
- External flows include:
- Git operations to prepare local commit data.
- GitHub integration for authenticating, pushing commits, and managing the remote repository.

##### Architectural Patterns and Principles
- Separation of Concerns: Distinct modules in the services folder handle specific responsibilities, ensuring that the system remains modular and each component has a clear purpose.
- Event-Driven / Reactive Design: File changes and user commands trigger workflows (such as starting/stopping tracking, scheduling commits, updating status).
- Integration with External APIs: Secure GitHub authentication and Git integration are key aspects.
- Testability: Presence of a tests directory indicates unit/integration testing practices.

##### Relevant Technologies, Frameworks, and Libraries
- TypeScript: The project uses TypeScript for type safety.
- VS Code API: For extension integration, UI components (status bar, dashboards) and secure authentication.
- Git and GitHub APIs: For version control and remote repository management.
- ESLint, Prettier, Mocha: Tools for code quality and testing (as seen in configuration files like .eslintrc.json, .mocharc.json).

##### Summary of Essential Elements to Capture
- Clear component labeling (Extension Host, Services, UI, External Dependencies).
- Modularity and layered architecture: extension activation, service orchestration, UI updates, and external communication with Git/GitHub.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "VS Code Extension Host"
        EH["Extension Host (src/extension.ts)"]:::extension
        QT["Quickstart (vsc-extension-quickstart.md)"]:::extension
    end

    subgraph "Services Layer"
        CA["Change Analyzer (src/services/changeAnalyzer.ts)"]:::service
        PC["Project Context (src/services/projectContext.ts)"]:::service
        SCH["Scheduler (src/services/scheduler.ts)"]:::service
        TR["Tracker (src/services/tracker.ts)"]:::service
        GC["Git Service (src/services/gitService.ts)"]:::service
        GH["GitHub Service (src/services/githubService.ts)"]:::service
        SG["Summary Generator (src/services/summaryGenerator.ts)"]:::service
        SP["Statistics Provider (src/services/statisticsProvider.ts)"]:::service
        SV["Statistics View (src/services/statisticsView.ts)"]:::service
        SB["Status Bar Manager (src/services/statusBarManager.ts)"]:::service
        WG["Website Generator (src/services/websiteGenerator.ts)"]:::service
    end

    subgraph "UI Components"
        CS["Coding Stats Dashboard (src/components/CodingStatsDashboard.tsx)"]:::ui
        UC["UI Card Component (src/components/ui/card.tsx)"]:::ui
    end

    subgraph "External Dependencies"
        GIT["Git"]:::external
        GHUB["GitHub"]:::external
    end

    %% Extension Host initiates services
    EH -->|"init"| CA
    EH -->|"init"| PC
    EH -->|"init"| SCH
    EH -->|"init"| SB
    EH -->|"init"| TR
    EH -->|"init"| SP

    %% Internal Services Interactions
    CA -->|"triggers"| SCH
    PC -->|"providesContext"| SCH
    PC -->|"providesContext"| TR
    SCH -->|"triggers"| TR
    TR -->|"calls"| GC
    TR -->|"calls"| GH
    TR -->|"generates"| SG
    TR -->|"invokes"| WG

    %% UI Updates from Services
    SP -->|"providesStats"| CS
    SV -->|"rendersStats"| CS
    SB -->|"updates"| CS

    %% External Communication
    GC -->|"executes"| GIT
    GH -->|"communicates"| GHUB

    %% Click Events
    click EH "https://github.com/teamial/devtrack/blob/main/src/extension.ts"
    click QT "https://github.com/teamial/devtrack/blob/main/vsc-extension-quickstart.md"
    click CS "https://github.com/teamial/devtrack/blob/main/src/components/CodingStatsDashboard.tsx"
    click UC "https://github.com/teamial/devtrack/blob/main/src/components/ui/card.tsx"
    click CA "https://github.com/teamial/devtrack/blob/main/src/services/changeAnalyzer.ts"
    click GC "https://github.com/teamial/devtrack/blob/main/src/services/gitService.ts"
    click GH "https://github.com/teamial/devtrack/blob/main/src/services/githubService.ts"
    click PC "https://github.com/teamial/devtrack/blob/main/src/services/projectContext.ts"
    click SCH "https://github.com/teamial/devtrack/blob/main/src/services/scheduler.ts"
    click SP "https://github.com/teamial/devtrack/blob/main/src/services/statisticsProvider.ts"
    click SV "https://github.com/teamial/devtrack/blob/main/src/services/statisticsView.ts"
    click SB "https://github.com/teamial/devtrack/blob/main/src/services/statusBarManager.ts"
    click SG "https://github.com/teamial/devtrack/blob/main/src/services/summaryGenerator.ts"
    click TR "https://github.com/teamial/devtrack/blob/main/src/services/tracker.ts"
    click WG "https://github.com/teamial/devtrack/blob/main/src/services/websiteGenerator.ts"

    %% Styles
    classDef extension fill:#f9c,stroke:#333,stroke-width:2px;
    classDef service fill:#ccf,stroke:#333,stroke-width:2px;
    classDef ui fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
```
