# jamiewhitney/fairways-core architecture

> Architecture diagram of the GitHub repository jamiewhitney/fairways-core, 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/jamiewhitney/fairways-core
- Repository: https://github.com/jamiewhitney/fairways-core

## Overview

Based on our analysis of the file tree and README, this project is a backend microservices system for a golf course management platform (Fairways). It consists of several Go-based microservices, each with a specific domain responsibility—such as pricing, booking, catalog, and tee time management—as well as a gRPC gateway that translates HTTP requests to gRPC calls. The project is containerized (with Docker and Kubernetes manifests), uses SQL migrations (with SQLC for query generation), and shares common components (via the pkg directory) for things like authentication, configuration, logging, and database connectivity.

##### Main Components
- Frontend/API Gateway:
- “gateway” service that exposes an HTTP endpoint and translates requests into gRPC calls.
- Backend Microservices:
- Bookings Service: Manages tee time bookings.
- Catalog Service: Handles course information.
- Pricing Service: Manages pricing rules (base and dynamic pricing).
- Tee Time Service: Generates available tee times and related pricing.
- Shared Components/Libraries:
- Common packages (pkg directory) that provide functionality such as authentication (auth-jwt), configuration, database connectivity (pkg/database), logging, caching, pubsub, and secret management.
- Database and Data Persistence:
- MySQL: Indicated in the build directory and migrations. Each service may use distinct repositories or schemas.
- Inter-Service Communication:
- gRPC interfaces as defined in the protobufs directory.
- The gRPC gateway as a facade to communicate with internal services.
- Infrastructure & Deployment:
- Containers (docker-compose, Dockerfile) and Kubernetes manifests (under deploy/kubernetes) illustrate the containerized deployment.
- Terraform manifests for infrastructure management.

##### Component Interactions and Data Flow
- For each microservice, show:
▪ Use of common packages (such as pubsub or secretstore) by each service.

##### Architectural Patterns and Design Principles
- Microservices architecture with clear service boundaries.
- That each microservice follows a layered structure (config, repository, service, and server) which may be represented as internal sub-components if desired.
- Use of code generation (SQLC and protobufs) and how that drives consistency in data access and service contracts.
- Separation between the HTTP API layer (managed by the gateway) and internal gRPC calls.

##### Relevant Technologies and Frameworks
- Go as the programming language for services.
- gRPC and Protocol Buffers for structured communication.
- MySQL as the database backend, with SQL migrations and SQLC-generated queries.
- Docker and Kubernetes for containerization and orchestration.
- Terraform for infrastructure management.
- Common tooling (e.g., logging, environment configuration, and secret stores like Vault or AWS Secrets Manager) as part of the supporting framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client("Client HTTP Request"):::client

    %% API Gateway
    APIGateway("API Gateway (gRPC)"):::service

    %% Backend Microservices Subgraph
    subgraph "Backend Microservices"
        direction TB
        Bookings("Bookings Service"):::service
        Catalog("Catalog Service"):::service
        Pricing("Pricing Service"):::service
        TeeTime("Tee Time Service"):::service
    end

    %% SQL Migrations Subgraph
    subgraph "SQL Migrations"
        direction TB
        BookingsM("Bookings Migrations"):::migration
        CatalogM("Catalog Migrations"):::migration
        PricingM("Pricing Migrations"):::migration
        TeeTimeM("Tee Time Migrations"):::migration
    end

    %% Database
    MySQL("MySQL Database"):::db

    %% Shared Components Subgraph
    subgraph "Shared Components"
        direction TB
        Auth("Auth-JWT"):::shared
        Config("Config"):::shared
        DBLibrary("Database Library"):::shared
        Env("Environment"):::shared
        Logging("Logging"):::shared
        Caching("Caching"):::shared
        PubSub("Pub/Sub"):::shared
        Internal("Internal Services"):::shared
        Secretstore("Secretstore"):::shared
        HTTPTransport("HTTP Transport"):::shared
    end

    %% gRPC & Protobuf Contracts
    Protobufs("gRPC & Protobuf Contracts"):::contract

    %% Deployment Infrastructure Subgraph
    subgraph "Deployment Infrastructure"
        direction TB
        Containers("Containers"):::infra
        Kubernetes("Kubernetes Manifests"):::infra
        Terraform("Terraform"):::infra
        SQLC("SQLC Config"):::infra
    end

    %% Connections
    Client -->|"sendsHTTPrequest"| APIGateway
    APIGateway -->|"translatestoGRPC"| Protobufs

    %% API Gateway calls Microservices
    APIGateway -->|"calls"| Bookings
    APIGateway -->|"calls"| Catalog
    APIGateway -->|"calls"| Pricing
    APIGateway -->|"calls"| TeeTime

    %% Protobufs used by Microservices
    Protobufs --> Bookings
    Protobufs --> Catalog
    Protobufs --> Pricing
    Protobufs --> TeeTime

    %% Microservices use SQL Migrations and then update Database
    Bookings -->|"uses"| BookingsM
    Catalog -->|"uses"| CatalogM
    Pricing -->|"uses"| PricingM
    TeeTime -->|"uses"| TeeTimeM

    BookingsM -->|"migratesto"| MySQL
    CatalogM -->|"migratesto"| MySQL
    PricingM -->|"migratesto"| MySQL
    TeeTimeM -->|"migratesto"| MySQL

    %% Shared Components usage by API Gateway and Microservices
    APIGateway -->|"uses"| HTTPTransport
    Bookings -->|"uses"| Auth
    Bookings -->|"uses"| Config
    Bookings -->|"uses"| DBLibrary
    Bookings -->|"logsWith"| Logging

    Catalog -->|"uses"| Auth
    Catalog -->|"uses"| Config
    Catalog -->|"uses"| DBLibrary
    Catalog -->|"logsWith"| Logging

    Pricing -->|"uses"| Auth
    Pricing -->|"uses"| Config
    Pricing -->|"uses"| DBLibrary
    Pricing -->|"logsWith"| Logging

    TeeTime -->|"uses"| Auth
    TeeTime -->|"uses"| Config
    TeeTime -->|"uses"| DBLibrary
    TeeTime -->|"logsWith"| Logging

    %% Deployment connections for services
    APIGateway -->|"deployedVia"| Containers
    Bookings -->|"deployedVia"| Containers
    Catalog -->|"deployedVia"| Containers
    Pricing -->|"deployedVia"| Containers
    TeeTime -->|"deployedVia"| Containers

    Containers -->|"orchestratedBy"| Kubernetes
    Kubernetes -->|"provisionedWith"| Terraform

    %% SQLC usage for query generation
    Bookings -->|"queryGeneratedBy"| SQLC
    Catalog -->|"queryGeneratedBy"| SQLC
    Pricing -->|"queryGeneratedBy"| SQLC
    TeeTime -->|"queryGeneratedBy"| SQLC

    %% Click Events for Components
    click APIGateway "https://github.com/jamiewhitney/fairways-core/tree/main/cmd/grpc-gateway"
    click Bookings "https://github.com/jamiewhitney/fairways-core/tree/main/cmd/bookings"
    click Catalog "https://github.com/jamiewhitney/fairways-core/tree/main/cmd/catalog"
    click Pricing "https://github.com/jamiewhitney/fairways-core/tree/main/cmd/pricing"
    click TeeTime "https://github.com/jamiewhitney/fairways-core/tree/main/cmd/tee-time"

    click Auth "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/auth-jwt"
    click Config "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/config"
    click DBLibrary "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/database"
    click Env "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/environment"
    click Logging "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/logging"
    click Caching "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/cache"
    click PubSub "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/pubsub"
    click Internal "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/internal-services"
    click Secretstore "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/secretstore"
    click HTTPTransport "https://github.com/jamiewhitney/fairways-core/tree/main/pkg/transport"

    click BookingsM "https://github.com/jamiewhitney/fairways-core/tree/main/migrations/bookings"
    click CatalogM "https://github.com/jamiewhitney/fairways-core/tree/main/migrations/catalog"
    click PricingM "https://github.com/jamiewhitney/fairways-core/tree/main/migrations/pricing"
    click TeeTimeM "https://github.com/jamiewhitney/fairways-core/tree/main/migrations/tee_time"

    click MySQL "https://github.com/jamiewhitney/fairways-core/tree/main/build/mysql"
    click Protobufs "https://github.com/jamiewhitney/fairways-core/tree/main/protobufs"
    click Containers "https://github.com/jamiewhitney/fairways-core/tree/main/build/docker"
    click Kubernetes "https://github.com/jamiewhitney/fairways-core/tree/main/deploy/kubernetes"
    click Terraform "https://github.com/jamiewhitney/fairways-core/tree/main/deploy/terraform"
    click SQLC "https://github.com/jamiewhitney/fairways-core/blob/main/sqlc.yaml"

    %% Styles
    classDef service fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef shared fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef db fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef infra fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef migration fill:#fadbd8,stroke:#a93226,stroke-width:2px;
    classDef client fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef contract fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
