# lazzerbeamstudios/spectra architecture

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

- Interactive diagram: https://gitdiagram.com/lazzerbeamstudios/spectra
- Repository: https://github.com/lazzerbeamstudios/spectra

## Overview

##### Project type and purpose
- This is a Go-based, monolithic backend API service (“api-v1”) that exposes REST endpoints for authentication (SignIn, SignUp), user profiles, and a home endpoint.
- It uses Ent (an ORM) and Atlas for schema migrations against a PostgreSQL database.
- It includes local collections (“collection-v1”) for API testing (Bruno scripts).
- Infrastructure is defined via Docker, Helm charts (“helm-v1”), Kubernetes manifests, and Terraform/OpenTofu (“opentofu-v1”) for provisioning on GCP (GKE).
- CI/CD workflows build, test, and push Docker images, then deploy to clusters via Helm/ArgoCD.

##### File structure
- Top level:
- api-v1/        – main Go service
- collection-v1/ – API test collections
- helm-v1/       – Helm chart and values for dev/stag/prod
- opentofu-v1/   – Terraform modules for GKE, VPC, GCP resources
- Dockerfile + docker-*.sh – container build scripts
- .github/workflows/*.yml – GitHub Actions (build, test, publish)
- Within api-v1:
- api.go (entry point)
- ent/       – generated ORM code, migrations, schema, hooks
- routes/    – handlers organized by feature (auth, users, home)
- mutations/ – business-logic layer
- utils/     – cross-cutting helpers (DB, Auth, Encode, GCP Files, Password)
- environment/ – loader for .env files (dev, docker)
- Infrastructure-as-code spans from local k3d clusters (k3d.yaml) to full GKE autopilot/standard Terraform.

##### Key README insights
- Dependencies: Go 1.23.6 (via asdf), Atlas CLI, ent code generator, Docker, k3d, Helm, ArgoCD, OpenTofu/Terraform, gcloud SDK.
- Common commands for running/migrating the database, generating ent code, and launching the API in various environments.

##### Diagramming conventions
- Use rectangles for compute components (API service, CI runner, Terraform controller).
- Blue for code/runtime (Go service)
- Green for infra components (K8s, Terraform)
- Orange for CI/CD (GitHub Actions, Docker Registry)
- Gray for utilities/external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Testing Tools
    subgraph "Clients & Testing Tools"
        direction TB
        WebClient["Web/Mobile Frontend"]:::external
        BrunoRunner["Bruno Script Runner"]:::external
    end

    %% API Service
    subgraph "API Service" 
        direction TB
        APIEntry["api-v1/api.go"]:::code
        subgraph "HTTP Router & Handlers"
            direction TB
            AuthRoutes["routes/auth_api/routes.go"]:::code
            SignIn["op-SignInAPI.go"]:::code
            SignUp["op-SignUpAPI.go"]:::code
            HomeRoutes["routes/home_api/routes.go"]:::code
            HomeGet["op-HomeGetAPI.go"]:::code
            UserRoutes["routes/users_api/routes.go"]:::code
            ProfileGet["op-ProfileGetAPI.go"]:::code
            ProfileUpdate["op-ProfileUpdateAPI.go"]:::code
            ProfileUpdateEmail["op-ProfileUpdateEmailAPI.go"]:::code
        end
        subgraph "Business Logic Layer"
            direction TB
            Mutations["mutations/user.go"]:::code
            Triggers["triggers/user.go"]:::code
        end
        subgraph "Data Access Layer"
            direction TB
            EntClient["ent/client.go"]:::code
            SchemaGen["ent/schema/user.go"]:::code
            EntGenerate["ent/generate.go"]:::code
            Migrations["ent/migrate/migrations/*.sql"]:::code
            Runtime["ent/runtime/runtime.go"]:::code
            Predicate["ent/predicate/predicate.go"]:::code
        end
        subgraph "Utilities"
            direction TB
            DBHelper["utils/db/ent.go"]:::code
            BunHelper["utils/db/bun.go"]:::code
            AuthUtil["utils/auth/auth.go"]:::code
            PasswordUtil["utils/password/password.go"]:::code
            EncodeUtil["utils/encode/encode.go"]:::code
            GCSUtil["utils/files/gcp.go"]:::code
        end
        subgraph "Configuration Loader"
            direction TB
            EnvLoader["environment/environment.go"]:::code
            DevEnv["dev.env"]:::code
            DockerEnv["docker.env"]:::code
        end
    end

    %% Data Stores & External Services
    subgraph "Data Stores & External Services"
        direction TB
        Postgres[(PostgreSQL Database)]:::infra
        GCS[(Google Cloud Storage)]:::infra
    end

    %% CI/CD & Infrastructure
    subgraph "CI/CD & Infrastructure"
        direction TB
        GitHubActions["GitHub Actions"]:::cicd
        GoTests["go-testing.yml"]:::cicd
        DockerBuild["docker-image.yml"]:::cicd
        DockerRegistry["Docker Registry"]:::cicd
        DockerfileNode["Dockerfile & Scripts"]:::infra
        DockerCompose["docker-api.yaml / docker-postgres.yaml"]:::infra
        LocalK8s["k3d.yaml"]:::infra
        HelmChart["helm-v1/Chart.yaml"]:::infra
        HelmValues["helm-v1/dev.yaml, stag.yaml, prod.yaml"]:::infra
        HelmTemplates["helm-v1/templates/*.yaml"]:::infra
        Terraform["opentofu-v1/*.tf"]:::infra
        GKECluster["Kubernetes Cluster (k3d / GKE)"]:::infra
        ArgoCD["ArgoCD Controller"]:::infra
    end

    %% Connections
    WebClient -->|HTTP| APIEntry
    BrunoRunner -->|HTTP| APIEntry

    APIEntry --> AuthRoutes
    AuthRoutes --> SignIn
    AuthRoutes --> SignUp
    APIEntry --> HomeRoutes
    HomeRoutes --> HomeGet
    APIEntry --> UserRoutes
    UserRoutes --> ProfileGet
    UserRoutes --> ProfileUpdate
    UserRoutes --> ProfileUpdateEmail

    SignIn --> Mutations
    SignUp --> Mutations
    ProfileUpdate --> Mutations
    ProfileUpdateEmail --> Mutations
    HomeGet --> Mutations
    Mutations --> EntClient
    Triggers --> EntClient

    EntClient --> Migrations
    EntClient --> Runtime
    EntClient --> Predicate
    EntClient --> SchemaGen
    EntClient --> EntGenerate

    APIEntry --> DBHelper
    APIEntry --> BunHelper
    APIEntry --> AuthUtil
    APIEntry --> PasswordUtil
    APIEntry --> EncodeUtil
    APIEntry --> GCSUtil

    APIEntry --> EnvLoader
    EnvLoader --> DevEnv
    EnvLoader --> DockerEnv

    APIEntry -->|SQL| Postgres
    APIEntry -->|SDK| GCS

    GitHubActions --> GoTests
    GitHubActions --> DockerBuild
    DockerBuild --> DockerfileNode
    DockerBuild --> DockerRegistry
    DockerRegistry --> HelmChart
    HelmChart --> HelmValues
    HelmChart --> HelmTemplates
    HelmTemplates -->|kubectl apply| GKECluster
    Terraform -->|provision| GKECluster
    LocalK8s -->|kubectl apply| GKECluster
    GKECluster --> ArgoCD

    GKECluster --> APIEntry

    %% Click Events
    click APIEntry "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/api.go"
    click AuthRoutes "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/auth_api/routes.go"
    click SignIn "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/auth_api/op-SignInAPI.go"
    click SignUp "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/auth_api/op-SignUpAPI.go"
    click HomeRoutes "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/home_api/routes.go"
    click HomeGet "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/home_api/op-HomeGetAPI.go"
    click UserRoutes "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/users_api/routes.go"
    click ProfileGet "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/users_api/op-ProfileGetAPI.go"
    click ProfileUpdate "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/users_api/op-ProfileUpdateAPI.go"
    click ProfileUpdateEmail "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/routes/users_api/op-ProfileUpdateEmailAPI.go"
    click Mutations "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/mutations/user.go"
    click Triggers "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/triggers/user.go"
    click EntClient "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/client.go"
    click SchemaGen "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/schema/user.go"
    click EntGenerate "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/generate.go"
    click Migrations "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/migrate/migrations/*.sql"
    click Runtime "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/runtime/runtime.go"
    click Predicate "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/ent/predicate/predicate.go"
    click DBHelper "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/db/ent.go"
    click BunHelper "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/db/bun.go"
    click AuthUtil "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/auth/auth.go"
    click PasswordUtil "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/password/password.go"
    click EncodeUtil "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/encode/encode.go"
    click GCSUtil "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/utils/files/gcp.go"
    click EnvLoader "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/environment/environment.go"
    click DevEnv "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/environment/dev.env"
    click DockerEnv "https://github.com/lazzerbeamstudios/spectra/blob/main/api-v1/environment/docker.env"
    click BrunoRunner "https://github.com/lazzerbeamstudios/spectra/blob/main/collection-v1/bruno.json"
    click GoTests "https://github.com/lazzerbeamstudios/spectra/blob/main/.github/workflows/go-testing.yml"
    click DockerBuild "https://github.com/lazzerbeamstudios/spectra/blob/main/.github/workflows/docker-image.yml"
    click DockerfileNode "https://github.com/lazzerbeamstudios/spectra/tree/main/Dockerfile"
    click DockerfileNode "https://github.com/lazzerbeamstudios/spectra/blob/main/docker_buildx.sh"
    click DockerfileNode "https://github.com/lazzerbeamstudios/spectra/blob/main/docker_tag.sh"
    click DockerCompose "https://github.com/lazzerbeamstudios/spectra/blob/main/docker-api.yaml"
    click DockerCompose "https://github.com/lazzerbeamstudios/spectra/blob/main/docker-postgres.yaml"
    click LocalK8s "https://github.com/lazzerbeamstudios/spectra/blob/main/k3d.yaml"
    click HelmChart "https://github.com/lazzerbeamstudios/spectra/blob/main/helm-v1/Chart.yaml"
    click HelmValues "https://github.com/lazzerbeamstudios/spectra/blob/main/helm-v1/dev.yaml"
    click HelmValues "https://github.com/lazzerbeamstudios/spectra/blob/main/helm-v1/stag.yaml"
    click HelmValues "https://github.com/lazzerbeamstudios/spectra/blob/main/helm-v1/prod.yaml"
    click HelmTemplates "https://github.com/lazzerbeamstudios/spectra/blob/main/helm-v1/templates/api.yaml"
    click Terraform "https://github.com/lazzerbeamstudios/spectra/blob/main/opentofu-v1/gke-autopilot.tf"
    click Terraform "https://github.com/lazzerbeamstudios/spectra/blob/main/opentofu-v1/gke-standard.tf"
    click Terraform "https://github.com/lazzerbeamstudios/spectra/blob/main/opentofu-v1/vpc.tf"
    click Terraform "https://github.com/lazzerbeamstudios/spectra/blob/main/opentofu-v1/google.tf"
    click Terraform "https://github.com/lazzerbeamstudios/spectra/blob/main/opentofu-v1/variables.tf"
    click GitHubActions "https://github.com/lazzerbeamstudios/spectra/blob/main/.github/workflows/go-testing.yml"
    click GitHubActions "https://github.com/lazzerbeamstudios/spectra/blob/main/.github/workflows/docker-image.yml"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef infra fill:#E2F0CB,stroke:#3A7E0D,color:#3A7E0D
    classDef cicd fill:#FFE2B3,stroke:#D97706,color:#D97706
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666
```
