# charly-js/colgit architecture

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

- Interactive diagram: https://gitdiagram.com/charly-js/colgit
- Repository: https://github.com/charly-js/colgit

## Overview

##### Project Overview
- That the project is a full-stack application built with Next.js 13 (using the App Router), React 18, and TypeScript on the frontend, and Next.js API routes on the backend.
- The platform supports version control, project management, real-time collaboration, and an AI assistant for code debugging.
- The underlying architectural style is hexagonal, which divides the system into domain (business logic), ports (interfaces), and adapters (implementations).

- User Interface Layer:
- “app” directory: Contains Next.js pages for different routes like activity, admin dashboard, calendar, login, profile, etc.
- “components”: A large set of reusable UI elements (e.g., navigation, chat, repository view, admin panels).
- “public”: Contains static assets like logos.
- Domain Layer:
- “domain” directory: Holds business entities for activity, admin, AI assistant, authentication, collaborators, and repository management. This is the heart of your business logic.
- Application Services:
- “services”: Contains service files (activity.service.ts, admin.service.ts, etc.) that orchestrate domain operations.
- Adapters (Infrastructure Layer):
- “adapters”: Implements concrete adapters for interfacing with various external systems (activity, admin, AI, auth, collaborator, repository), following the port and adapter pattern.
- Database Component:
- “col-git (db)”: Contains configuration, migrations, seeds, and other database-related setup. It’s distinct from the main application code and represents the persistence/storage layer.
- Additional Modules (Utilities & Configuration):
- “lib”, “utils”, “hooks”, and “docs”: Provide supporting utilities, UI hooks, and configuration setups (such as theme, translations).

##### Relationships and Interactions
- Surround the domain with the ‘ports’ layer (conceptually) that includes interfaces used by both the UI and infrastructure layers.
- Adapters connected to the ports:
- Adapters (in the “adapters” folder) provide external integrations for authentication, repository management, AI interactions, etc.
- Communication flows:
- UI components (from “app” and “components”) invoke actions on the backend APIs.
- API routes (in “app/api”) act as controllers that call the underlying services.
- Services execute business logic in the domain and interact with the adapters, which then read/write to the database (“col-git (db)”).
- External integrations (e.g., OpenAI for AI-assisted debugging) can also be marked as external systems interfaced through specific adapters.

##### Architectural Patterns and Important Design Principles
- Core Domain: “domain” logic.
- Ports: Abstract interfaces (these might not be a physical folder but are conceptually implemented by the adapters).
- Adapters: “adapters” directory provides concrete implementations bridging external services and frameworks.
- Separation between presentation (UI – “app” and “components”), business logic (domain and services), and persistence (database folder “col-git (db)”).
- Mention that the project leverages TypeScript and follows a modular design so that responsibilities are clearly demarcated.

##### Diagramming Tools & Detail Level
- Every component is clearly labeled.
- Use annotations to emphasize key interactions such as authentication flows, AI assistance integration, and repository management processes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (UI Layer)"
        UI_Next["Next.js Pages"]:::ui
        UI_Components["React Components"]:::ui
    end

    %% Backend Layer
    subgraph "Backend (Application Layer)"
        API["API Routes"]:::backend
        Services["Application Services"]:::backend
        Domain["Domain (Business Logic)"]:::domain
        Adapters["Adapters (External Interfaces)"]:::adapter
        Database["Database (Persistence)"]:::db
        External["External Service\n(e.g., OpenAI)"]:::adapter
    end

    %% Support Modules
    subgraph "Support Modules"
        Lib["Lib (Utilities & Config)"]:::support
        Hooks["Hooks (UI hooks)"]:::support
        Utils["Utils (Helpers)"]:::support
        Docs["Docs (Documentation)"]:::support
    end

    %% Connections
    UI_Next -->|"calls"| API
    UI_Components -->|"calls"| API
    API -->|"orchestrates"| Services
    Services -->|"executes"| Domain
    Domain -->|"integrates with"| Adapters
    Adapters -->|"persists to"| Database
    Adapters -->|"calls"| External

    %% Support Modules providing utilities to various layers
    Lib ---|"supports"| UI_Next
    Lib ---|"supports"| Services
    Hooks ---|"enhances"| UI_Components
    Utils ---|"assists"| Services
    Docs ---|"guides"| Domain

    %% Click Events for Component Mapping
    click UI_Next "https://github.com/charly-js/colgit/tree/main/app"
    click UI_Components "https://github.com/charly-js/colgit/tree/main/components"
    click Domain "https://github.com/charly-js/colgit/tree/main/domain"
    click Services "https://github.com/charly-js/colgit/tree/main/services"
    click Adapters "https://github.com/charly-js/colgit/tree/main/adapters"
    click Database "https://github.com/charly-js/colgit/tree/main/col-git (db)"
    click Lib "https://github.com/charly-js/colgit/tree/main/lib"
    click Hooks "https://github.com/charly-js/colgit/tree/main/hooks"
    click Utils "https://github.com/charly-js/colgit/tree/main/utils"
    click Docs "https://github.com/charly-js/colgit/tree/main/docs"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px,rx:5,ry:5;
    classDef backend fill:#F9E79F,stroke:#7D6608,stroke-width:2px,rx:5,ry:5;
    classDef domain fill:#F5B7B1,stroke:#943126,stroke-width:2px,rx:50,ry:20;
    classDef adapter fill:#D5F5E3,stroke:#196F3D,stroke-width:2px,rx:5,ry:5;
    classDef db fill:#FAD7A0,stroke:#B9770E,stroke-width:2px,rx:5,ry:5;
    classDef support fill:#D6EAF8,stroke:#2874A6,stroke-width:2px,rx:5,ry:5;
```
