Skip to content
Huddle

Overview

The API service is the central authority of the Huddle platform. It owns business logic, identity, persistence, and object storage, and acts as the Temporal client that triggers every background workflow. Almost every other service reads its data through the generated SDK that this service produces.

  • Language: Go 1.26
  • Web framework: Echo v5
  • Database: PostgreSQL via pgx v5, typed with sqlc
  • Migrations: goose
  • Cache / rate-limit: Redis
  • Object storage: S3-compatible (Tigris), presigned URLs
  • API docs: swaggo/swag v2 → OpenAPI, from which the TypeScript and Python SDKs are generated

Project structure

Section titled “Project structure”
  • Directorycmd/
    • Directoryserver/ API server entry point
      • …
    • Directorymigrate/ goose-backed migrate CLI (up / status / reset)
      • …
    • Directorynuke/ Env-atomic reset — rollback → migrate → seed (embedded seed.json)
      • …
  • Directorydb/ Unified SQL tree — see the note below
    • 0NN_<schema>_<table>.migration.sql goose migration (also the sqlc schema)
    • 0NN_<schema>_<table>.query.sql sqlc query source
    • embed.go Embeds the migrations for cmd/migrate
    • docker-compose.yaml Local Postgres + Redis
  • Directoryinternal/
    • Directoryapi/ Echo HTTP layer — routes, middleware, handlers
      • …
    • Directoryservice/ Business logic (core impls + decorators), one dir per domain (auth, bond, premium, document, project, audit)
      • Directorybond/pdf/ pdfcpu wrapper — trim / merge / render / seal-stamp bond forms
        • …
    • Directorydb/ sqlc-generated persistence code
      • …
    • Directorymodel/ Domain types, enums, and FromDB converters
      • …
    • Directoryauthn/ Session JWT minting + purpose model
      • …
    • Directoryauthz/ RBAC — Action/Check/ScopeOrgs (enforced; see Architecture)
      • …
    • Directoryaudit/ Audit logging
      • …
    • Directoryworkflow/ Temporal client wrapper + status Watcher
      • …
    • Directorycache/ Redis wrapper (behind EnableCache)
      • …
    • Directoryo11y/ OpenTelemetry + Temporal identity propagation
      • …
    • Directorycrypt/ Transparent AES-GCM encryption for PII columns
      • …
    • Directorystorage/ S3 client + presigning
      • …
    • Directoryid/ ULID type (stored as Postgres uuid)
      • …
    • Directoryconfig/ Viper-backed config
      • …
    • Directoryutils/ Context helpers, generic Map
      • …
  • Directorydocs/ Generated OpenAPI spec (docs.go, swagger.json)
    • …
  • Directoryscripts/
    • openapi_query.jq Rewrites the spec for QUERY endpoints (see Architecture)
  • sqlc.yaml sqlc configuration
  • .sql-formatter.json sql-formatter config (formats *.query.sql)
  • .swaggo swag type overrides

Reference

Section titled “Reference”