# tingtt/hackbar-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/tingtt/hackbar-copilot
- Repository: https://github.com/tingtt/hackbar-copilot

## Overview

##### Main Components
a. Frontend Client:
- Located in the “client” folder.
- Contains UI components (Provider.tsx, index.ts, etc.), tooling for code generation (interface.gen, query.gen, etc.) and configuration files.
- Communicates to the backend via GraphQL queries and mutations.
b. API Server / Backend:
- Startup entry points in “cmd/registry” (and a secondary “cmd/tui” for alternative interfaces).
- Responsible for exposing the GraphQL playground (http://localhost:8080/playground) and handling API calls.
c. GraphQL Layer:
- Found under “internal/interface-adapter/handler/graphql”.
- Contains the GraphQL schema, resolvers, adapters (for example, authentication, menu, order, recipe, stock, user) that directly bind client requests to internal business logic.
d. Application & Usecase Layer:
- Implemented in “internal/usecase” and “internal/usecase/copilot” and others.
- Contains business logic routines such as processing orders, managing recipes, and handling cashout and checkout.
e. Domain Layer:
- Under “internal/domain”, this layer defines the core business entities and types for several domains (recipe, order, menu, stock, etc.).
- Includes validations, transformations, and domain-specific logic.
f. Infrastructure Layer:
- Found in “internal/infrastructure”, where the actual data persistence is handled.
- Provides implementations (e.g., using a filesystem-based datasource with TOML encoding) that the domain and usecase layers utilize.
g. External Integrations and Tools:
- Dockerfile, .dockerignore, CI configurations (.github/workflows), and additional tooling in the “client/tools” folder suggest containerized deployment and automated processes.
- The README quickly shows how to start the registry server and access the playground.

##### Relationships and Interactions
- The frontend client makes GraphQL queries and mutations to the API server.
- The API server (with its GraphQL handler) routes requests to the corresponding usecase functions.
- The usecase layer interacts with the domain layer where business rules and validations are applied.
- For data persistence or external data interactions, the usecase layer calls into the infrastructure layer, which implements filesystem or TOML-based storage.

##### Architectural Patterns and Design Principles
- Clean Architecture / Hexagonal Architecture: Separate concerns via layers (interface adapters, usecase, domain, and infrastructure).
- GraphQL as a communication/interaction pattern between client and backend.
- Dependency inversion where high-level modules (domain, usecase) do not depend on infrastructure specifics, which are plugged in via adapters.
- Additionally, note the tooling for code generation in the client, ensuring the client can properly and consistently interface with the backend API.

##### Technologies, Frameworks, and Libraries
- Go is the primary language for the backend – using modules (go.mod, go.sum) and a directory structure that hints at industry best practices.
- GraphQL is used for the API, evidenced by the GraphQL schema and resolver files.
- For the client, modern JavaScript/TypeScript tooling is evident (Prettier, ESLint, TSConfig) which might align with popular frontend frameworks.
- Docker and CI/CD configurations indicate containerized deployment and automated builds/releases.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend Client"]:::frontend
    end

    %% API Server / Backend Entry Points
    subgraph "API Server Layer"
        REG["API Registry (cmd/registry)"]:::backend
        TUI["API TUI (cmd/tui)"]:::backend
    end

    %% GraphQL Layer
    subgraph "GraphQL Layer"
        GQL["GraphQL API Handler"]:::graphql
    end

    %% Application & Usecase Layer
    subgraph "Usecase Layer"
        UC["Application & Usecase Layer"]:::usecase
        CP["Copilot Usecase"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        DOM["Domain Models"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        INF["Infrastructure Layer"]:::infrastructure
    end

    %% External Integrations & Tools
    subgraph "External Integrations & Tools"
        DOC["Dockerfile"]:::external
        DIGN[".dockerignore"]:::external
        WF["CI/CD Workflows"]:::external
        CTS["Client Tools"]:::external
    end

    %% Connections for primary request flow (vertical)
    FE -->|"sends GraphQL requests"| REG
    FE -->|"sends GraphQL requests"| TUI
    REG -->|"routes to"| GQL
    TUI -->|"routes to"| GQL
    GQL -->|"invokes"| UC
    GQL -->|"invokes"| CP
    UC -->|"applies business rules to"| DOM
    CP -->|"applies business rules to"| DOM
    UC -->|"persists data via"| INF
    CP -->|"persists data via"| INF

    %% Connections for external integrations (dotted lines)
    FE -.->|"uses"| CTS
    REG -.->|"integrates with"| DOC
    REG -.->|"integrates with"| DIGN
    REG -.->|"integrates with"| WF

    %% Click Events
    click FE "https://github.com/tingtt/hackbar-copilot/tree/main/client/"
    click DOC "https://github.com/tingtt/hackbar-copilot/tree/main/Dockerfile"
    click DIGN "https://github.com/tingtt/hackbar-copilot/blob/main/.dockerignore"
    click WF "https://github.com/tingtt/hackbar-copilot/tree/main/.github/workflows"
    click CTS "https://github.com/tingtt/hackbar-copilot/tree/main/client/tools"
    click REG "https://github.com/tingtt/hackbar-copilot/tree/main/cmd/registry"
    click TUI "https://github.com/tingtt/hackbar-copilot/tree/main/cmd/tui"
    click GQL "https://github.com/tingtt/hackbar-copilot/tree/main/internal/interface-adapter/handler/graphql"
    click UC "https://github.com/tingtt/hackbar-copilot/tree/main/internal/usecase"
    click CP "https://github.com/tingtt/hackbar-copilot/tree/main/internal/usecase/copilot"
    click DOM "https://github.com/tingtt/hackbar-copilot/tree/main/internal/domain"
    click INF "https://github.com/tingtt/hackbar-copilot/tree/main/internal/infrastructure"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef graphql fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef usecase fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef domain fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef infrastructure fill:#fefefe,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
