# salvador-lopez/vehicle-sharing-go architecture

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

- Interactive diagram: https://gitdiagram.com/salvador-lopez/vehicle-sharing-go
- Repository: https://github.com/salvador-lopez/vehicle-sharing-go

## Overview

Based on our analysis of both the file tree and README, we know that this project – “vehicle-sharing-go” – is a multiapplication monorepo written in Go for managing a vehicle sharing system. The system design is centered around a vehicle inventory domain and uses a Domain-Driven Design approach, splitting concerns across several distinct executable components (such as a REST API, a domain event consumer, and a message relay) while sharing common domain logic and infrastructure packages.

##### Main Components
- REST API Service: Under app/inventory/cmd/vehicle/rest-api-goa, this service provides HTTP endpoints (with Goa) for interacting with the vehicle sharing system.
- Domain Event Consumer: Located at app/inventory/cmd/vehicle/domain-event-consumer, this component consumes domain events (i.e. updates, notifications) to act upon changes in vehicle data.
- Message Relay Service: Found at app/inventory/cmd/vehicle/message-relay, this handles the relaying or publishing of messages between services.
- Core Domain / Business Logic: The internal/vehicle directory contains domain definitions, command handling, projections, and repository logic (both in-memory and via GORM for relational mapping). Additionally, the pkg directory provides shared utilities such as database connection management and domain models.
- Database: Dockers under app/inventory/docker/mysql and docker-compose.yml define the MySQL database(s) used for persistence.
- Infrastructure & Shared Libraries: The pkg directory contains common building blocks including domain event publishing, database infrastructure (with outbox pattern support), and integration test suites.

##### Relationships and Interactions
- The REST API exposes endpoints to clients, receives requests, and communicates with the core domain layer located in internal/vehicle.
- The Domain Event Consumer listens for vehicle-related events produced by changes in the system. These events might be published by business logic and then acted upon downstream.
- The Message Relay picks up messages (possibly from the event publisher or from an outbox table in the database) and forwards them to external systems or other parts of the application.
- Both the domain event consumer and message relay interact with the core domain and repository layers to update projections and maintain consistency.
- The system uses a database (MySQL) for persistent storage, accessed either via GORM-based repositories (or using in-memory alternatives for tests or lighter operations).

##### Architectural Patterns and Design Principles
- Domain-Driven Design (DDD): The separation into directories like domain, command, and internal business logic for vehicles reflects a layered DDD approach.
- CQRS & Event-Driven Architecture: The existence of a separate domain event consumer, message relay, and clear separation between read and write models (notably in the GORM database implementations and projection code) indicate this pattern.
- Micro-application / Multientry Approach: Different Go applications (cmd packages) serve different purposes while sharing common internal and pkg modules.
- Containerization: Docker configurations show that containerized deployment is a central part of the system’s operational design (e.g., MySQL container, REST API container).

##### Relevant Technologies, Frameworks, and Libraries
- Go Language – with standard Go modules (go.mod, go.work).
- Goa – for designing and implementing the REST API.
- GORM – for object-relational mapping in the persistence layer.
- Docker / docker-compose – for local development and containerized deployment.
- Custom domain event handling mechanisms and integration tests for robust deployment.

##### Essential Elements
- Clear labels for each service/component:
- “REST API (Goa based)”
- “Domain Event Consumer”
- “Message Relay Service”
- “Vehicle Domain Core (Internal Layer)”
- “Shared Infrastructure/Database Layer (MySQL, GORM interface)”
- Data flow from clients to the REST API, and outbound calls within the backend to the domain logic.
- Events produced by changes in the REST API or core business logic flow to the event consumer and message relay.
- Interactions between the domain logic and the database.
- Configuration hints such as “docker-compose” to hint at the container orchestration environment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        C["Clients"]:::client
        RESTAPI["REST API (Goa based)"]:::rest
    end

    subgraph "Business Logic"
        DomainCore["Vehicle Domain Core (Internal Layer)"]:::core
    end

    subgraph "Event Processing"
        DomainEventConsumer["Domain Event Consumer"]:::event
        MessageRelay["Message Relay Service"]:::event
    end

    subgraph "Persistence Layer"
        MySQLDatabase["Database (MySQL/GORM)"]:::database
    end

    subgraph "Shared Services"
        SharedInfra["Infrastructure & Shared Libraries"]:::shared
    end

    %% Connections
    C -->|"HTTP_request"| RESTAPI
    RESTAPI -->|"calls_business_logic"| DomainCore
    DomainCore -->|"reads/writes"| MySQLDatabase
    DomainCore -->|"publishes_event"| DomainEventConsumer
    DomainCore -->|"publishes_event"| MessageRelay
    DomainEventConsumer -->|"updates_projection"| MySQLDatabase
    MessageRelay -->|"retrieves_data"| MySQLDatabase
    DomainCore -.->|"utilizes"| SharedInfra
    RESTAPI -.->|"uses"| SharedInfra

    %% Click Events
    click RESTAPI "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/app/inventory/cmd/vehicle/rest-api-goa"
    click DomainEventConsumer "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/app/inventory/cmd/vehicle/domain-event-consumer"
    click MessageRelay "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/app/inventory/cmd/vehicle/message-relay"
    click DomainCore "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/app/inventory/internal/vehicle"
    click MySQLDatabase "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/app/inventory/docker/mysql"
    click SharedInfra "https://github.com/salvador-lopez/vehicle-sharing-go/tree/main/pkg"

    %% Styles
    classDef client fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef rest fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef core fill:#FFB6C1,stroke:#C71585,stroke-width:2px;
    classDef event fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef database fill:#D3D3D3,stroke:#696969,stroke-width:2px,stroke-dasharray: 5 5;
    classDef shared fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px,stroke-dasharray: 3 3;
    
    %% Additional styling for arrows if needed (optional)
    linkStyle default stroke:#555,stroke-width:1.5px;
```
