# hejmsdz/goslides architecture

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

- Interactive diagram: https://gitdiagram.com/hejmsdz/goslides
- Repository: https://github.com/hejmsdz/goslides

## Overview

#### Purpose and Entry Points
This is a Go backend for managing church/liturgy content, songs, teams, users, live sessions, and presentation decks. Application startup is rooted at `main.go`, with HTTP server setup in `app/server.go`. Dependency construction is centralized in `di/dependencies.go`.

#### HTTP API Layer
Feature-specific routers expose the API boundary and translate HTTP requests into service calls:
- Authentication and bootstrap: `routers/auth_router.go`, `routers/bootstrap_router.go`
- Liturgy, live operation, and presentation decks: `routers/liturgy_router.go`, `routers/live_router.go`, `routers/deck_router.go`
- Content and administration: `routers/songs_router.go`, `routers/teams_router.go`, `routers/users_router.go`

Routers should remain the request/response boundary; DTOs in `dtos/` represent transport-facing payloads and error shapes.

#### Domain Services
Business workflows are organized by feature in `services/`. These services are the primary control-flow layer between routers, domain models, repositories, and rendering utilities:
- Authentication, including Google authentication: `services/auth_service.go`, `services/google_auth_service.go`
- Liturgy and live-state orchestration: `services/liturgy_service.go`, `services/live_service.go`
- Song, team, user, and deck workflows: `services/songs_service.go`, `services/teams_service.go`, `services/deck_service.go`

#### Persistence and State Boundaries
The repository layer defines persistence abstractions and multiple implementations:
- Liturgy state: `repos/liturgy_repo.go`, `repos/redis_liturgy_repo.go`, `repos/memory_liturgy_repo.go`
- Live-session state: `repos/live_repo.go`, `repos/redis_live_repo.go`, `repos/memory_live_repo.go`
- Authentication nonces: `repos/nonce_repo.go`, `repos/redis_nonce_repo.go`, `repos/sql_nonce_repo.go`

This indicates Redis-backed ephemeral/shared state with memory implementations for local or fallback use, while nonce persistence can use SQL. Database and Redis connection setup are isolated in `database/db.go` and `database/redis.go`.

#### Domain and API Contracts
Domain entities are grouped by business area in `models/`, including `models/live_models.go`, `models/songs_models.go`, and `models/teams_models.go`. External API contracts are separated into DTO files such as `dtos/liturgy_dtos.go`, `dtos/live_dtos.go`, and `dtos/deck_dtos.go`. This separation is an important boundary: services should map transport DTOs to domain models rather than exposing storage shapes directly.

#### Rendering and Document Generation
Presentation/document concerns are isolated from HTTP and persistence:
- PDF generation: `core/pdf.go`
- Typesetting/layout: `core/typesetting.go`
- Tugal-related rendering/content logic: `core/tugal.go`

`services/deck_service.go` likely coordinates deck workflows with these core rendering facilities. Fonts are supplied from `fonts/`, and generated/public-facing artifacts are expected under `public/`.

#### Runtime and Infrastructure
The runtime is Go, defined by `go.mod` and launched through `main.go`. Container deployment is supported by `Dockerfile`; development reload configuration is in `.air.toml`. External infrastructure materially includes a SQL database, Redis, and Google-based authentication. CI is configured at `.github/workflows/ci.yml`.

Main entry points: [`routers/liturgy_router.go`](https://github.com/hejmsdz/goslides/blob/main/routers/liturgy_router.go) (Feature routers), [`services/auth_service.go`](https://github.com/hejmsdz/goslides/blob/main/services/auth_service.go) (Authentication), [`services/liturgy_service.go`](https://github.com/hejmsdz/goslides/blob/main/services/liturgy_service.go) (Liturgy & live workflows), [`repos/redis_liturgy_repo.go`](https://github.com/hejmsdz/goslides/blob/main/repos/redis_liturgy_repo.go) (Redis state repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Application entry<br/>Go entrypoint<br/>[main.go]"))
  node_server["HTTP server<br/>server setup<br/>[server.go]"]
  node_dependencies["Dependency wiring<br/>composition root<br/>[dependencies.go]"]
end

subgraph group_api["HTTP API"]
  node_routers["Feature routers<br/>HTTP handlers<br/>[liturgy_router.go]"]
  node_dtos["API DTOs<br/>transport contracts<br/>[liturgy_dtos.go]"]
end

subgraph group_services["Domain Services"]
  node_auth["Authentication<br/>domain service<br/>[auth_service.go]"]
  node_liturgy_live["Liturgy &amp; live workflows<br/>domain services<br/>[liturgy_service.go]"]
  node_content_admin["Content &amp; administration<br/>domain services<br/>[songs_service.go]"]
  node_deck["Deck workflows<br/>domain service<br/>[deck_service.go]"]
  node_models["Domain models<br/>entities<br/>[live_models.go]"]
end

subgraph group_state["Persistence &amp; State"]
  node_liturgy_repo["Liturgy state contract<br/>repository interface<br/>[liturgy_repo.go]"]
  node_live_repo["Live state contract<br/>repository interface<br/>[live_repo.go]"]
  node_nonce_repo["Nonce contract<br/>repository interface<br/>[nonce_repo.go]"]
  node_redis_state["Redis state repositories<br/>repository implementations"]
  node_memory_state["Memory state repositories<br/>repository implementations"]
  node_sql_nonce["SQL nonce repository<br/>repository implementation<br/>[sql_nonce_repo.go]"]
  node_redis[("Redis connection<br/>infrastructure client<br/>[redis.go]")]
  node_sql[("SQL database connection<br/>infrastructure client<br/>[db.go]")]
end

subgraph group_rendering["Rendering"]
  node_rendering["PDF &amp; typesetting<br/>rendering core<br/>[pdf.go]"]
  node_fonts_public["Fonts &amp; public artifacts<br/>rendering assets"]
end

node_google{{"Google authentication<br/>external identity provider"}}

node_main -->|"builds"| node_dependencies
node_dependencies -->|"configures"| node_server
node_server -->|"mounts"| node_routers
node_routers -->|"reads and returns"| node_dtos
node_routers -->|"auth requests"| node_auth
node_routers -->|"liturgy/live requests"| node_liturgy_live
node_routers -->|"content/admin requests"| node_content_admin
node_routers -->|"deck requests"| node_deck
node_auth -->|"uses"| node_models
node_liturgy_live -->|"uses"| node_models
node_content_admin -->|"uses"| node_models
node_deck -->|"uses"| node_models
node_liturgy_live -->|"persists state through"| node_liturgy_repo
node_liturgy_live -->|"persists state through"| node_live_repo
node_auth -->|"stores nonces through"| node_nonce_repo
node_auth -->|"delegates identity to"| node_google
node_deck -->|"generates with"| node_rendering
node_rendering -->|"uses and emits"| node_fonts_public
node_liturgy_repo -.->|"implemented by"| node_redis_state
node_liturgy_repo -.->|"implemented by"| node_memory_state
node_live_repo -.->|"implemented by"| node_redis_state
node_live_repo -.->|"implemented by"| node_memory_state
node_nonce_repo -.->|"implemented by"| node_redis_state
node_nonce_repo -.->|"implemented by"| node_sql_nonce
node_redis_state -->|"uses"| node_redis
node_sql_nonce -->|"uses"| node_sql

click node_main "https://github.com/hejmsdz/goslides/blob/main/main.go"
click node_server "https://github.com/hejmsdz/goslides/blob/main/app/server.go"
click node_dependencies "https://github.com/hejmsdz/goslides/blob/main/di/dependencies.go"
click node_routers "https://github.com/hejmsdz/goslides/blob/main/routers/liturgy_router.go"
click node_dtos "https://github.com/hejmsdz/goslides/blob/main/dtos/liturgy_dtos.go"
click node_auth "https://github.com/hejmsdz/goslides/blob/main/services/auth_service.go"
click node_liturgy_live "https://github.com/hejmsdz/goslides/blob/main/services/liturgy_service.go"
click node_content_admin "https://github.com/hejmsdz/goslides/blob/main/services/songs_service.go"
click node_deck "https://github.com/hejmsdz/goslides/blob/main/services/deck_service.go"
click node_models "https://github.com/hejmsdz/goslides/blob/main/models/live_models.go"
click node_liturgy_repo "https://github.com/hejmsdz/goslides/blob/main/repos/liturgy_repo.go"
click node_live_repo "https://github.com/hejmsdz/goslides/blob/main/repos/live_repo.go"
click node_nonce_repo "https://github.com/hejmsdz/goslides/blob/main/repos/nonce_repo.go"
click node_redis_state "https://github.com/hejmsdz/goslides/blob/main/repos/redis_liturgy_repo.go"
click node_memory_state "https://github.com/hejmsdz/goslides/blob/main/repos/memory_liturgy_repo.go"
click node_sql_nonce "https://github.com/hejmsdz/goslides/blob/main/repos/sql_nonce_repo.go"
click node_redis "https://github.com/hejmsdz/goslides/blob/main/database/redis.go"
click node_sql "https://github.com/hejmsdz/goslides/blob/main/database/db.go"
click node_rendering "https://github.com/hejmsdz/goslides/blob/main/core/pdf.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_server,node_dependencies toneBlue
class node_routers,node_dtos toneAmber
class node_auth,node_liturgy_live,node_content_admin,node_deck,node_models toneMint
class node_liturgy_repo,node_live_repo,node_nonce_repo,node_redis_state,node_memory_state,node_sql_nonce,node_redis,node_sql toneRose
class node_rendering,node_fonts_public toneIndigo
class node_google toneNeutral
```

## Components

### Runtime

- [Application entry](https://github.com/hejmsdz/goslides/blob/main/main.go): Go entrypoint · `main.go`
- [HTTP server](https://github.com/hejmsdz/goslides/blob/main/app/server.go): server setup · `app/server.go`
- [Dependency wiring](https://github.com/hejmsdz/goslides/blob/main/di/dependencies.go): composition root · `di/dependencies.go`

### HTTP API

- [Feature routers](https://github.com/hejmsdz/goslides/blob/main/routers/liturgy_router.go): HTTP handlers · Auth, bootstrap, liturgy, live, deck, songs, teams, and users endpoints. · `routers/liturgy_router.go`
- [API DTOs](https://github.com/hejmsdz/goslides/blob/main/dtos/liturgy_dtos.go): transport contracts · `dtos/liturgy_dtos.go`

### Domain Services

- [Authentication](https://github.com/hejmsdz/goslides/blob/main/services/auth_service.go): domain service · Includes Google authentication workflow. · `services/auth_service.go`
- [Liturgy & live workflows](https://github.com/hejmsdz/goslides/blob/main/services/liturgy_service.go): domain services · `services/liturgy_service.go`
- [Content & administration](https://github.com/hejmsdz/goslides/blob/main/services/songs_service.go): domain services · Song, team, and user workflows. · `services/songs_service.go`
- [Deck workflows](https://github.com/hejmsdz/goslides/blob/main/services/deck_service.go): domain service · `services/deck_service.go`
- [Domain models](https://github.com/hejmsdz/goslides/blob/main/models/live_models.go): entities · Business entities for live sessions, songs, teams, and related content. · `models/live_models.go`

### Persistence & State

- [Liturgy state contract](https://github.com/hejmsdz/goslides/blob/main/repos/liturgy_repo.go): repository interface · `repos/liturgy_repo.go`
- [Live state contract](https://github.com/hejmsdz/goslides/blob/main/repos/live_repo.go): repository interface · `repos/live_repo.go`
- [Nonce contract](https://github.com/hejmsdz/goslides/blob/main/repos/nonce_repo.go): repository interface · `repos/nonce_repo.go`
- [Redis state repositories](https://github.com/hejmsdz/goslides/blob/main/repos/redis_liturgy_repo.go): repository implementations · Shared ephemeral liturgy, live-session, and nonce state. · `repos/redis_liturgy_repo.go`
- [Memory state repositories](https://github.com/hejmsdz/goslides/blob/main/repos/memory_liturgy_repo.go): repository implementations · Local or fallback liturgy and live state. · `repos/memory_liturgy_repo.go`
- [SQL nonce repository](https://github.com/hejmsdz/goslides/blob/main/repos/sql_nonce_repo.go): repository implementation · `repos/sql_nonce_repo.go`
- [Redis connection](https://github.com/hejmsdz/goslides/blob/main/database/redis.go): infrastructure client · `database/redis.go`
- [SQL database connection](https://github.com/hejmsdz/goslides/blob/main/database/db.go): infrastructure client · `database/db.go`

### Rendering

- [PDF & typesetting](https://github.com/hejmsdz/goslides/blob/main/core/pdf.go): rendering core · Generates presentation and document output. · `core/pdf.go`
- **Fonts & public artifacts**: rendering assets

### Other components

- **Google authentication**: external identity provider

## Connections

- Application entry → Dependency wiring: builds
- Dependency wiring → HTTP server: configures
- HTTP server → Feature routers: mounts
- Feature routers → API DTOs: reads and returns
- Feature routers → Authentication: auth requests
- Feature routers → Liturgy & live workflows: liturgy/live requests
- Feature routers → Content & administration: content/admin requests
- Feature routers → Deck workflows: deck requests
- Authentication → Domain models: uses
- Liturgy & live workflows → Domain models: uses
- Content & administration → Domain models: uses
- Deck workflows → Domain models: uses
- Liturgy & live workflows → Liturgy state contract: persists state through
- Liturgy & live workflows → Live state contract: persists state through
- Authentication → Nonce contract: stores nonces through
- Authentication → Google authentication: delegates identity to
- Deck workflows → PDF & typesetting: generates with
- PDF & typesetting → Fonts & public artifacts: uses and emits
- Liturgy state contract → Redis state repositories: implemented by
- Liturgy state contract → Memory state repositories: implemented by
- Live state contract → Redis state repositories: implemented by
- Live state contract → Memory state repositories: implemented by
- Nonce contract → Redis state repositories: implemented by
- Nonce contract → SQL nonce repository: implemented by
- Redis state repositories → Redis connection: uses
- SQL nonce repository → SQL database connection: uses