# ardanlabs/service architecture

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

- Interactive diagram: https://gitdiagram.com/ardanlabs/service
- Repository: https://github.com/ardanlabs/service

## Overview

##### Main Components
- Frontend/API Layer:
- The “api” folder contains subdirectories for “frontends” (specifically an admin frontend built with web technologies like Vue.js) and service endpoints (e.g., auth, metrics, sales).
- The “api/tooling” directory covers command-line tools or admin utilities.
- Service Layer:
- Domain and Application Logic:
- The “app” directory contains domain-specific subdirectories (authapp, checkapp, homeapp, oauthapp, productapp, etc.) and SDK components. This layer implements business rules and service logic.
- Business Logic:
- The “business” directory further refines the domain logic into “domain” (homebus, productbus, userbus, vproductbus) with associated business rules and even test utilities.
- Foundation and Infrastructure:
- The “foundation” directory provides lower-level modules for handling cross-cutting concerns: Docker and deployment scripts, keystore management, logging, Open Telemetry (otel), web request handling, and background processing (workers).
- Deployment and Operational Aspects:
- Directories like “.circleci”, “zarf” (with Kubernetes and Docker configurations), and “makefile” support Continuous Integration/Deployment, containerization, and orchestration in Kubernetes.

##### Understand the Relationships & Flow
- The frontend (for example, the “admin” frontend) interacts with the backend API endpoints.
- API services (auth, metrics, sales) communicate with the underlying application (“app”) and business (“business”) layers. In many cases, the API layer is simply a presentation or interface layer that delegates to lower-level logic.
- The domain logic in “app” is structured to isolate business rules. In addition, the “business” layer may handle more refined or enterprise-level rules (for example, in “homebus” or “productbus”).
- Shared components in “foundation” provide utilities, middleware, and support services such as logging or metrics, ensuring that components are decoupled and follow best practices.
- The use of tooling and configuration (e.g., Docker configurations in “zarf”, CI/CD configs in “.circleci”, and the makefile for task automation) is integral for deployment and operational management.

##### Architectural Patterns & Key Practices Noted
- Domain Driven Design: Emphasis on distinct “domain” packages and clearly separated logic for each bounded context (auth, home, product, user, etc.).
- Data Oriented Architecture: The separation between raw/app, business, and sdk packages shows the importance of handling data and its transformations cleanly.
- Microservices and Separation of Concerns: The “api/services” directory shows how different service components (authentication, metrics, sales) are handled as independent units.
- Infrastructure as Code & Kubernetes Integration: The “zarf” directory with Kubernetes manifests and Dockerfiles highlights a containerized, orchestrated design.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend / API Layer
    subgraph "Frontend / API Layer"
        direction TB
        A1["Admin Frontend"]:::ui
        subgraph "API Services"
            direction TB
            B1["Auth Service"]:::service
            B2["Metrics Service"]:::service
            B3["Sales Service"]:::service
        end
        A3["Admin Tooling"]:::service
    end

    %% Application & Business Layer
    subgraph "Application & Business Layer"
        direction TB
        C1["Domain/Application Logic"]:::domain
        C2["Business Logic"]:::domain
    end

    %% Foundation / Infrastructure Layer
    subgraph "Foundation / Infrastructure"
        direction TB
        D1["Foundation Components (Logging,Middleware,etc.)"]:::infra
    end

    %% Deployment & Operational Layer
    subgraph "Deployment & Operational"
        direction TB
        E1["CI/CD"]:::deploy
        E2["Containerization & Kubernetes"]:::deploy
        E3["Task Automation"]:::deploy
    end

    %% Connections between layers
    %% Frontend to API Services
    A1 -->|"calls"| B1
    A1 -->|"calls"| B2
    A1 -->|"calls"| B3
    A3 -->|"assists"| A1

    %% API Services to Domain/Application Logic
    B1 -->|"delegates"| C1
    B2 -->|"delegates"| C1
    B3 -->|"delegates"| C1

    %% Domain to Business Logic
    C1 -->|"appliesRules"| C2

    %% Foundation supports all layers (dashed arrows)
    D1 --- A1
    D1 --- B1
    D1 --- B2
    D1 --- B3
    D1 --- C1
    D1 --- C2

    %% Deployment configuration supports Foundation
    E1 -->|"configures"| D1
    E2 -->|"deploysTo"| D1
    E3 -->|"automates"| D1

    %% Click Events
    click A1 "https://github.com/ardanlabs/service/tree/master/api/frontends/admin"
    click B1 "https://github.com/ardanlabs/service/tree/master/api/services/auth"
    click B2 "https://github.com/ardanlabs/service/tree/master/api/services/metrics"
    click B3 "https://github.com/ardanlabs/service/tree/master/api/services/sales"
    click A3 "https://github.com/ardanlabs/service/tree/master/api/tooling/admin"
    click C1 "https://github.com/ardanlabs/service/tree/master/app/domain"
    click C2 "https://github.com/ardanlabs/service/tree/master/business/domain"
    click D1 "https://github.com/ardanlabs/service/tree/master/foundation"
    click E1 "https://github.com/ardanlabs/service/blob/master/.circleci"
    click E2 "https://github.com/ardanlabs/service/tree/master/zarf"
    click E3 "https://github.com/ardanlabs/service/tree/master/makefile"

    %% Styles
    classDef ui fill:#f9e79f,stroke:#f39c12,stroke-width:2px,color:#000;
    classDef service fill:#aed6f1,stroke:#3498db,stroke-width:2px,color:#000;
    classDef domain fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,color:#000;
    classDef infra fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px,color:#000;
    classDef deploy fill:#d2b4de,stroke:#8e44ad,stroke-width:2px,color:#000;
```
