# dedeez14/goforge architecture

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

- Interactive diagram: https://gitdiagram.com/dedeez14/goforge
- Repository: https://github.com/dedeez14/goforge

## Overview

goforge is a Clean-Architecture Go API blueprint. Its principal workflow is an HTTP request entering the Fiber server, reaching a routed handler and transport-agnostic use case, then using domain repository interfaces backed by PostgreSQL; the handler returns a common response envelope. The application composition root wires these layers and the platform feature packs. The README documents additional opt-in capabilities. Some are represented at package level because their integration details were not sampled; those relationships are shown only where the excerpts or README support them.

Main entry points: [`internal/app/app.go`](https://github.com/dedeez14/goforge/blob/main/internal/app/app.go) (Composition root), [`internal/adapter/http/handler`](https://github.com/dedeez14/goforge/tree/main/internal/adapter/http/handler) (HTTP handlers), [`pkg/realtime/sse.go`](https://github.com/dedeez14/goforge/blob/main/pkg/realtime/sse.go) (SSE bridge), [`internal/infrastructure/server/server.go`](https://github.com/dedeez14/goforge/blob/main/internal/infrastructure/server/server.go) (Fiber server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entry"]
  node_api["API entrypoint<br/>[main.go]"]
  node_server["Fiber server<br/>[server.go]"]
  node_router["Route registration<br/>[router.go]"]
  node_handlers["HTTP handlers"]
  node_middleware["HTTP middleware"]
end

subgraph group_core["API core"]
  node_usecases["Business use cases"]
  node_auth["Authentication flow<br/>[auth.go]"]
  node_sessions["Session management<br/>[session.go]"]
  node_domain["Domain models"]
end

subgraph group_infra["Infrastructure"]
  node_postgres["Postgres repositories"]
  node_sessionrepo["Session repository<br/>[session.go]"]
  node_database[("PostgreSQL")]
  node_security["Security services"]
  node_composition["Composition root<br/>[app.go]"]
end

subgraph group_platform["Platform features"]
  node_modules["Module system"]
  node_idempotency["Idempotency"]
  node_outbox["Transactional outbox<br/>[outbox.go]"]
  node_events["Event bus<br/>[bus.go]"]
  node_realtime["SSE bridge<br/>[sse.go]"]
  node_openapi["OpenAPI and docs<br/>[openapi.go]"]
  node_adminui["Bundled admin UI"]
end

subgraph group_operations["Operations"]
  node_observability["Metrics and tracing"]
  node_tenant["Tenant primitives"]
  node_flags["Feature flags"]
  node_forge["Forge CLI"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_server
node_api -->|"starts"| node_composition
node_composition -->|"configures"| node_server
node_composition -->|"registers routes"| node_router
node_server -->|"installs"| node_middleware
node_router -->|"routes to"| node_handlers
node_handlers -->|"calls"| node_usecases
node_handlers -->|"reads identity"| node_middleware
node_usecases -->|"uses interfaces"| node_domain
node_sessions -->|"calls repository"| node_sessionrepo
node_sessionrepo -->|"reads and writes"| node_database
node_composition -->|"wires repositories"| node_postgres
node_composition -->|"wires services"| node_security
node_composition -->|"builds platform"| node_modules
node_composition -->|"builds platform"| node_idempotency
node_composition -->|"builds platform"| node_outbox
node_composition -->|"builds platform"| node_realtime
node_composition -->|"registers spec"| node_openapi
node_composition -->|"mounts UI"| node_adminui
node_composition -->|"configures metrics"| node_observability
node_realtime -->|"streams events"| node_events
node_outbox -->|"publishes events"| node_events
node_realtime -->|"scopes streams"| node_tenant
node_client -.->|"invokes commands"| node_forge
node_client -.->|"configures features"| node_flags

click node_api "https://github.com/dedeez14/goforge/blob/main/cmd/api/main.go"
click node_server "https://github.com/dedeez14/goforge/blob/main/internal/infrastructure/server/server.go"
click node_router "https://github.com/dedeez14/goforge/blob/main/internal/infrastructure/server/router.go"
click node_handlers "https://github.com/dedeez14/goforge/tree/main/internal/adapter/http/handler"
click node_middleware "https://github.com/dedeez14/goforge/tree/main/internal/adapter/http/middleware"
click node_usecases "https://github.com/dedeez14/goforge/tree/main/internal/usecase"
click node_auth "https://github.com/dedeez14/goforge/blob/main/internal/usecase/auth.go"
click node_sessions "https://github.com/dedeez14/goforge/blob/main/internal/usecase/session.go"
click node_domain "https://github.com/dedeez14/goforge/tree/main/internal/domain"
click node_postgres "https://github.com/dedeez14/goforge/tree/main/internal/adapter/repository/postgres"
click node_sessionrepo "https://github.com/dedeez14/goforge/blob/main/internal/adapter/repository/postgres/session.go"
click node_security "https://github.com/dedeez14/goforge/tree/main/internal/infrastructure/security"
click node_composition "https://github.com/dedeez14/goforge/blob/main/internal/app/app.go"
click node_modules "https://github.com/dedeez14/goforge/tree/main/pkg/module"
click node_idempotency "https://github.com/dedeez14/goforge/tree/main/pkg/idempotency"
click node_outbox "https://github.com/dedeez14/goforge/blob/main/pkg/outbox/outbox.go"
click node_events "https://github.com/dedeez14/goforge/blob/main/pkg/events/bus.go"
click node_realtime "https://github.com/dedeez14/goforge/blob/main/pkg/realtime/sse.go"
click node_openapi "https://github.com/dedeez14/goforge/blob/main/pkg/openapi/openapi.go"
click node_adminui "https://github.com/dedeez14/goforge/tree/main/pkg/adminui"
click node_observability "https://github.com/dedeez14/goforge/tree/main/pkg/observability"
click node_tenant "https://github.com/dedeez14/goforge/tree/main/pkg/tenant"
click node_flags "https://github.com/dedeez14/goforge/tree/main/pkg/flags"
click node_forge "https://github.com/dedeez14/goforge/tree/main/cmd/forge"

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_api,node_server,node_router,node_handlers,node_middleware,node_client toneBlue
class node_usecases,node_auth,node_sessions,node_domain toneAmber
class node_postgres,node_sessionrepo,node_database,node_security,node_composition toneMint
class node_modules,node_idempotency,node_outbox,node_events,node_realtime,node_openapi,node_adminui toneRose
class node_observability,node_tenant,node_flags,node_forge toneIndigo
```

## Components

### HTTP entry

- [API entrypoint](https://github.com/dedeez14/goforge/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Fiber server](https://github.com/dedeez14/goforge/blob/main/internal/infrastructure/server/server.go): `internal/infrastructure/server/server.go`
- [Route registration](https://github.com/dedeez14/goforge/blob/main/internal/infrastructure/server/router.go): `internal/infrastructure/server/router.go`
- [HTTP handlers](https://github.com/dedeez14/goforge/tree/main/internal/adapter/http/handler): `internal/adapter/http/handler`
- [HTTP middleware](https://github.com/dedeez14/goforge/tree/main/internal/adapter/http/middleware): `internal/adapter/http/middleware`

### API core

- [Business use cases](https://github.com/dedeez14/goforge/tree/main/internal/usecase): `internal/usecase`
- [Authentication flow](https://github.com/dedeez14/goforge/blob/main/internal/usecase/auth.go): `internal/usecase/auth.go`
- [Session management](https://github.com/dedeez14/goforge/blob/main/internal/usecase/session.go): `internal/usecase/session.go`
- [Domain models](https://github.com/dedeez14/goforge/tree/main/internal/domain): `internal/domain`

### Infrastructure

- [Postgres repositories](https://github.com/dedeez14/goforge/tree/main/internal/adapter/repository/postgres): `internal/adapter/repository/postgres`
- [Session repository](https://github.com/dedeez14/goforge/blob/main/internal/adapter/repository/postgres/session.go): `internal/adapter/repository/postgres/session.go`
- **PostgreSQL**
- [Security services](https://github.com/dedeez14/goforge/tree/main/internal/infrastructure/security): `internal/infrastructure/security`
- [Composition root](https://github.com/dedeez14/goforge/blob/main/internal/app/app.go): `internal/app/app.go`

### Platform features

- [Module system](https://github.com/dedeez14/goforge/tree/main/pkg/module): `pkg/module`
- [Idempotency](https://github.com/dedeez14/goforge/tree/main/pkg/idempotency): `pkg/idempotency`
- [Transactional outbox](https://github.com/dedeez14/goforge/blob/main/pkg/outbox/outbox.go): `pkg/outbox/outbox.go`
- [Event bus](https://github.com/dedeez14/goforge/blob/main/pkg/events/bus.go): `pkg/events/bus.go`
- [SSE bridge](https://github.com/dedeez14/goforge/blob/main/pkg/realtime/sse.go): `pkg/realtime/sse.go`
- [OpenAPI and docs](https://github.com/dedeez14/goforge/blob/main/pkg/openapi/openapi.go): `pkg/openapi/openapi.go`
- [Bundled admin UI](https://github.com/dedeez14/goforge/tree/main/pkg/adminui): `pkg/adminui`

### Operations

- [Metrics and tracing](https://github.com/dedeez14/goforge/tree/main/pkg/observability): `pkg/observability`
- [Tenant primitives](https://github.com/dedeez14/goforge/tree/main/pkg/tenant): `pkg/tenant`
- [Feature flags](https://github.com/dedeez14/goforge/tree/main/pkg/flags): `pkg/flags`
- [Forge CLI](https://github.com/dedeez14/goforge/tree/main/cmd/forge): `cmd/forge`

### Other components

- **API client**

## Connections

- API client → Fiber server: sends requests (evidence: `README.md`)
- API entrypoint → Composition root: starts (evidence: `cmd/api/main.go`)
- Composition root → Fiber server: configures (evidence: `internal/app/app.go`)
- Composition root → Route registration: registers routes (evidence: `internal/app/app.go`)
- Fiber server → HTTP middleware: installs (evidence: `internal/infrastructure/server/server.go`)
- Route registration → HTTP handlers: routes to (evidence: `internal/infrastructure/server/router.go`)
- HTTP handlers → Business use cases: calls (evidence: `internal/adapter/http/handler/auth.go`)
- HTTP handlers → HTTP middleware: reads identity (evidence: `internal/adapter/http/handler/auth.go`)
- Business use cases → Domain models: uses interfaces (evidence: `README.md`)
- Session management → Session repository: calls repository (evidence: `internal/usecase/session.go`)
- Session repository → PostgreSQL: reads and writes (evidence: `internal/adapter/repository/postgres/session.go`)
- Composition root → Postgres repositories: wires repositories (evidence: `internal/app/app.go`)
- Composition root → Security services: wires services (evidence: `internal/app/app.go`)
- Composition root → Module system: builds platform (evidence: `internal/app/app.go`)
- Composition root → Idempotency: builds platform
- Composition root → Transactional outbox: builds platform
- Composition root → SSE bridge: builds platform
- Composition root → OpenAPI and docs: registers spec (evidence: `internal/app/app.go`)
- Composition root → Bundled admin UI: mounts UI
- Composition root → Metrics and tracing: configures metrics (evidence: `internal/app/app.go`)
- SSE bridge → Event bus: streams events (evidence: `pkg/realtime/sse.go`)
- Transactional outbox → Event bus: publishes events (evidence: `pkg/outbox/outbox.go`)
- SSE bridge → Tenant primitives: scopes streams (evidence: `pkg/realtime/sse.go`)
- API client → Forge CLI: invokes commands (evidence: `README.md`)
- API client → Feature flags: configures features (evidence: `README.md`)
