# elyseemb/relay-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/elyseemb/relay-compiler
- Repository: https://github.com/elyseemb/relay-compiler

## Overview

##### Project Type and Purpose
- This is a full-stack web application using Preact+Relay on the client and Go (gqlgen) on the server, backed by PostgreSQL.
- The front end fetches data from a GraphQL API implemented in Go; the API layer lives under pkg/server/api/console/v1.

##### File Structure Analysis
- assets/…: Preact source (App.tsx, components, hooks), Relay artifacts (__generated__), Vite config.
- cmd/relay-compiler/: custom Go binary to run Relay codegen.
- pkg/server/: Go HTTP server split into
- public/…: compiled static assets (Vite output) served to the browser
- web/: page handlers (templates/Layout.templ)
- api/console/v1/: GraphQL schema, resolver, sign-up handler
- pkg/services, pkg/coredata, pkg/db, pkg/crypto, pkg/usrmgr: service layer, data layer (entities, migrations), DB connection, password hashing, tenant/user management.
- compose/: Docker Compose definitions for Postgres, Prometheus, Grafana, Tempo.
- internal/tools: build-time tools (e.g., gqlgen).

##### README Insights
- Confirms Preact+Relay front end consuming a GraphQL API built in Go with gqlgen.

##### Main Components
a. Client (Browser):
- Preact app compiled by Vite, uses Relay to fetch queries/mutations.
b. API Gateway (Go HTTP Server):
- Static file handler (serves assets)
- GraphQL HTTP endpoint (/console/v1) implemented via gqlgen
- Web handlers for server-side templates
c. Business Logic Layer (Services):
- pkg/services, pkg/usrmgr orchestrate operations (create user, manage sessions)
d. Data Access Layer:
- pkg/coredata: entity definitions and migrations
- pkg/db: connection pooling, configuration
e. Persistence:
- PostgreSQL
f. Security Middleware:
- pkg/crypto/passwdhash, pkg/secureCookie for password hashing and cookie management
g. Observability Stack (Docker Compose):
- Prometheus (metrics scraping)
- Grafana (dashboards)
- Tempo (distributed tracing)

##### Relationships and Data Flow
- The browser sends Relay GraphQL requests → Go HTTP server.
- GraphQL resolver delegates to service layer → data layer → DB.
- Responses bubble back through resolver → Relay → Preact UI.
- Static assets are served directly from Go public/ or via Vite in dev.
- Observability agents within the Go server emit metrics/traces to Prometheus/Tempo; Grafana queries Prometheus.

##### Architectural Patterns & Principles
- Layered architecture: Presentation (assets + GraphQL client) → API/Handler → Service → Data → DB.
- Separation of concerns:
- Codegen tools (gqlgen, Relay compiler) isolated in cmd/ and config files.
- Database migrations kept under pkg/coredata/migrations.
- Infrastructure as code: Docker Compose for spinning up dependencies.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Frontend Layer
  subgraph "Frontend (Preact+Relay)" 
    direction TB
    Browser["Browser"]:::frontend
    StaticEntry["index.html"]:::frontend
    Vite["Vite Build (assets)"]:::frontend
    App["App.tsx"]:::frontend
    MainTS["main.tsx"]:::frontend
    Components["components/"]:::frontend
    Hooks["hooks/"]:::frontend
    RelayProv["RelayProviders.tsx"]:::frontend
    Generated["__generated__/"]:::frontend
  end

  %% API Server Layer
  subgraph "API Server (Go HTTP)" 
    direction TB
    APIserver["server.go"]:::server
    subgraph "Static Asset Handler"
      StaticHandler["public/assets/.vite/"]:::server
      JSFiles["main-*.js"]:::server
      CSSFiles["main-*.css"]:::server
    end
    subgraph "GraphQL API /console/v1"
      GraphQLEndpoint["schema.graphql / gqlgen"]:::server
      Resolver["resolver.go"]:::server
      V1Resolver["v1_resolver.go"]:::server
      SignUp["sign_up_handler.go"]:::server
      Types["types.go"]:::server
    end
    subgraph "Web Templates"
      LayoutTempl["Layout.templ"]:::server
      LayoutGo["Layout_templ.go"]:::server
      WebPage["web.go"]:::server
    end
  end

  %% Service & Data Layer
  subgraph "Service & Data" 
    direction TB
    Services["service.go"]:::business
    UserMgr["usrmgr.go"]:::business
    subgraph "Core Data"
      EntityReg["entity_type_reg.go"]:::business
      SessionEnt["session.go"]:::business
      UserEnt["user.go"]:::business
      Migrations["migrations/"]:::business
    end
    subgraph "DB Layer"
      DBConn["connection.go"]:::business
      AuthConfig["auth_config.go"]:::business
      PGConfig["pg_config.go"]:::business
    end
    subgraph "Security"
      PasswdHash["passwdhash.go"]:::business
      SecureCookie["secureCookie.go"]:::business
    end
  end

  %% Database
  Postgres[(PostgreSQL)]:::database

  %% Codegen Tools
  subgraph "Codegen & Build Tools"
    direction TB
    RelayCompiler["relay-compiler"]:::codegen
    GqlgenTool["gqlgen.yml"]:::codegen
    Tools["tools.go"]:::codegen
    RelayConfig["relay.config.json"]:::codegen
  end

  %% Observability
  subgraph "Observability" 
    direction TB
    Prometheus["Prometheus"]:::observ
    Grafana["Grafana"]:::observ
    Tempo["Tempo"]:::observ
  end

  %% Compose
  Compose["compose.yml"]:::observ

  %% Connections
  Browser -->|"fetch(/console/v1)"| GraphQLEndpoint
  Browser -->|"load index.html"| StaticEntry
  Browser -->|"load assets"| StaticHandler
  Vite -->|build| StaticHandler
  RelayCompiler -->|generates| Generated
  GqlgenTool -->|generates| Resolver
  APIserver -->|serves| StaticHandler
  APIserver -->|handles| GraphQLEndpoint
  APIserver -->|renders| WebPage
  GraphQLEndpoint -->|calls| Resolver
  Resolver -->|->| Services
  Services -->|uses| CoreData
  Services -->|uses| DBLayer
  Services -->|uses| Security
  DBLayer -->|SQL over TLS| Postgres
  APIserver -->|metrics| Prometheus
  Tempo -->|traces| APIserver
  Grafana -->|queries| Prometheus

  %% Click Events
  click App "https://github.com/elyseemb/relay-compiler/blob/main/assets/App.tsx"
  click MainTS "https://github.com/elyseemb/relay-compiler/blob/main/assets/main.tsx"
  click Components "https://github.com/elyseemb/relay-compiler/tree/main/assets/components/"
  click Hooks "https://github.com/elyseemb/relay-compiler/tree/main/assets/hooks/"
  click RelayProv "https://github.com/elyseemb/relay-compiler/blob/main/assets/providers/RelayProviders.tsx"
  click Generated "https://github.com/elyseemb/relay-compiler/tree/main/assets/__generated__/"
  click StaticEntry "https://github.com/elyseemb/relay-compiler/blob/main/index.html"
  click Vite "https://github.com/elyseemb/relay-compiler/blob/main/vite.config.ts"
  click RelayCompiler "https://github.com/elyseemb/relay-compiler/blob/main/cmd/relay-compiler/main.go"
  click APIserver "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/server.go"
  click GraphQLEndpoint "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/schema.graphql"
  click Resolver "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/resolver.go"
  click V1Resolver "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/v1_resolver.go"
  click SignUp "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/sign_up_handler.go"
  click Types "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/types/types.go"
  click StaticHandler "https://github.com/elyseemb/relay-compiler/tree/main/pkg/server/public/assets/.vite/"
  click LayoutTempl "https://github.com/elyseemb/relay-compiler/blob/main/templates/Layout.templ"
  click LayoutGo "https://github.com/elyseemb/relay-compiler/blob/main/templates/Layout_templ.go"
  click WebPage "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/web/web.go"
  click Services "https://github.com/elyseemb/relay-compiler/blob/main/pkg/services/service.go"
  click UserMgr "https://github.com/elyseemb/relay-compiler/blob/main/pkg/usrmgr/usrmgr.go"
  click EntityReg "https://github.com/elyseemb/relay-compiler/blob/main/pkg/coredata/entity_type_reg.go"
  click SessionEnt "https://github.com/elyseemb/relay-compiler/blob/main/pkg/coredata/session.go"
  click UserEnt "https://github.com/elyseemb/relay-compiler/blob/main/pkg/coredata/user.go"
  click Migrations "https://github.com/elyseemb/relay-compiler/tree/main/pkg/coredata/migrations/"
  click DBConn "https://github.com/elyseemb/relay-compiler/blob/main/pkg/db/connection.go"
  click AuthConfig "https://github.com/elyseemb/relay-compiler/blob/main/pkg/db/auth_config.go"
  click PGConfig "https://github.com/elyseemb/relay-compiler/blob/main/pkg/db/pg_config.go"
  click PasswdHash "https://github.com/elyseemb/relay-compiler/blob/main/pkg/crypto/passwdhash/passwdhash.go"
  click SecureCookie "https://github.com/elyseemb/relay-compiler/blob/main/pkg/secureCookie/secureCookie.go"
  click Tools "https://github.com/elyseemb/relay-compiler/blob/main/internal/tools/tools.go"
  click RelayConfig "https://github.com/elyseemb/relay-compiler/blob/main/relay.config.json"
  click GqlgenTool "https://github.com/elyseemb/relay-compiler/blob/main/pkg/server/api/console/v1/gqlgen.yml"
  click Prometheus "https://github.com/elyseemb/relay-compiler/blob/main/compose/prometheus/prometheus.yaml"
  click Grafana "https://github.com/elyseemb/relay-compiler/blob/main/compose/grafana/provisioning/datasources/datasources.yaml"
  click Tempo "https://github.com/elyseemb/relay-compiler/blob/main/compose/tempo/tempo.yaml"
  click Compose "https://github.com/elyseemb/relay-compiler/blob/main/compose.yml"

  %% Styles
  classDef frontend fill:#e0f7fa,stroke:#0277bd,color:#000
  classDef server fill:#e8f5e9,stroke:#2e7d32,color:#000
  classDef business fill:#fff3e0,stroke:#ef6c00,color:#000
  classDef database fill:#eceff1,stroke:#546e7a,color:#000
  classDef observ fill:#fff8e1,stroke:#f57c00,color:#000,stroke-dasharray: 5 5
  classDef codegen fill:#f3e5f5,stroke:#6a1b9a,color:#000
```
