kurious/docs/ARCHITECTURE.md

Architecture

Patterns

Hexagonal Architecture (Ports & Adapters)

The project follows hexagonal architecture — business logic lives at the center and all I/O (databases, HTTP, external APIs) is pushed to the periphery through interfaces. The domain never imports infrastructure packages.

┌─────────────────────────────────────────────────────┐
│  Ports (delivery mechanisms)                         │
│    ports/http/       — HTTP server (gorilla/mux)     │
│    ports/background/ — Cron jobs (robfig/cron)       │
└──────────────────────┬──────────────────────────────┘
                       │ depends on
┌──────────────────────▼──────────────────────────────┐
│  Application layer (use cases)                      │
│    app/command/   — write-side handlers             │
│    app/query/     — read-side handlers              │
│    decorator/     — handler interfaces + logging     │
└──────────────────────┬──────────────────────────────┘
                       │ depends on
┌──────────────────────▼──────────────────────────────┐
│  Domain (pure business rules)                        │
│    domain/  — entities (Course, Organization, ...)    │
│    domain/  — repository interfaces (ports)          │
│    domain/  — mapper interface (CourseMapper)        │
└──────────────────────┬──────────────────────────────┘
                       │ implemented by
┌──────────────────────▼──────────────────────────────┐
│  Adapters (infrastructure)                           │
│    adapters/sqlite_*_repository.go — SQLite repos     │
│    adapters/memory_mapper.go      — in-memory mapper │
│    adapters/ydb_*                 — legacy YDB stubs │
│    adapters/not_implemented.go    — sentinel stubs  │
└─────────────────────────────────────────────────────┘

CQRS (Command-Query Responsibility Segregation)

The application layer splits all use cases into commands (writes) and queries (reads), each with its own handler type:

• Commands implement decorator.CommandHandler[T] — Handle(ctx, params) error
• Queries implement decorator.QueryHandler[Q, U] — Handle(ctx, query) (result, error)

Both are aggregated into app.Application{Commands, Queries} and exposed through service.Application.

Decorator Pattern

Every handler is wrapped with a logging + tracing decorator at construction time (decorator.ApplyCommandDecorators / decorator.AddQueryDecorators). The decorator:

1. Creates an OpenTelemetry span ("command <Name>" / "query <Name>")
2. Logs structured fields (handler name, serialized args)
3. Measures elapsed time
4. Records errors on the span
5. Delegates to the base handler

The decorator is applied inside New*Handler() constructors — callers never see the raw handler.

Composition Root

service.NewApplication is the single place where all wiring happens: it selects the DB engine, creates connections, instantiates adapters, registers handlers on the Application struct, and injects the CourseMapper. Binaries in cmd/ call this function.

Repository Interface Segregation

Each aggregate has its own repository interface defined in domain/:

Interface	Methods (key)
CourseRepository	List, Get, GetByExternalID, Create, CreateBatch, Delete, UpdateCourseDescription, ListStatistics
OrganizationRepository	List, Get, ListStats, Create, Delete
LearningCategoryRepository	List, Get, Upsert

Adapters implement these interfaces. Unimplemented methods use ErrNotImplemented sentinel stubs.

External Client Abstraction

The sravni.ru HTTP client (common/client/sravni/Client interface) is abstracted behind an interface with a noop.Client fallback. The background sync handler depends on the interface, not the concrete HTTP implementation.

Logic Placement

Concern	Where it lives
Business entities	internal/kurious/domain/
Repository interfaces (ports)	internal/kurious/domain/repository.go
Mapper interface	internal/kurious/domain/mapper.go
Write-side use cases	internal/kurious/app/command/
Read-side use cases	internal/kurious/app/query/
Handler interfaces + decorators	internal/common/decorator/
Repository implementations	internal/kurious/adapters/
HTTP routing + handlers	internal/kurious/ports/http/
Templ templates	internal/kurious/ports/http/bootstrap/*.templ
Background jobs	internal/kurious/ports/background/
Composition root	internal/kurious/service/service.go
HTTP client (sravni.ru)	internal/common/client/sravni/
Config structs	internal/common/config/
Error sentinels	internal/common/errors/
Logging helpers	internal/common/xcontext/, common/xlog/
Utility functions	internal/common/xslices/, common/nullable/
ID generation	internal/common/generator/
Entry points (binaries)	cmd/kuriweb/, cmd/background/, cmd/dev/
SQL migrations	migrations/sqlite/ (embedded via go:embed)
Static web assets	assets/kurious/static/ (embedded via go:embed)
Public package	pkg/xdefault/

Layers

1. Domain Layer (internal/kurious/domain/)

Pure Go types — no framework imports, no I/O. Contains:

• Entities: Course, Organization, LearningCategory — structs with fields and no behavior beyond data representation.
• Repository interfaces: CourseRepository, OrganizationRepository, LearningCategoryRepository — the ports that adapters must implement.
• Mapper interface: CourseMapper — maps external dictionary IDs to human-readable names; implemented by adapters/memory_mapper.go.
• Value objects: SourceType, ListCoursesParams, CreateCourseParams, etc. — parameter types used by repository interfaces.

2. Application Layer (internal/kurious/app/)

Orchestrates domain objects through repository ports:

• app.go — Application{Commands, Queries} aggregate struct. Groups all handlers into a single type.
• command/ — Write handlers: CreateCourse, CreateCourses, DeleteCourse, UpdateCourseDescription, CreateOrganization. Each is a struct holding repository dependencies, with a New*Handler() constructor that wraps the base with decorators.
• query/ — Read handlers: GetCourse, ListCourses, ListLearningTypes, ListCourseThematics, ListCoursesStats, ListOrganizations, ListOrganizationsStats, GetOrganization. Some queries (e.g. ListCourses) implement cursor-based pagination with configurable batch sizes.

3. Common Infrastructure (internal/common/)

Shared packages used across the application:

• decorator/ — Generic CommandHandler[T] and QueryHandler[Q, U] interfaces + logging/tracing decorator implementations. Uses OpenTelemetry spans and structured slog logging.
• client/sravni/ — HTTP client for sravni.ru with Client interface, noop.Client fallback, entities, and helpers. Uses go-resty internally.
• config/ — Typed config structs: Log, HTTP, Sqlite, Trace, YDB, Duration.
• errors/ — SimpleError, ValidationError, sentinel errors (ErrNotFound, ErrNotImplemented). Mapped to HTTP status codes in ports/http.
• xslices/ — Generic slice utilities: Map, Filter, ForEach, LRU.
• nullable/ — Generic Value[T] for nullable fields (wraps a value + valid flag).
• xcontext/ — Context helpers for propagating request-scoped log fields.
• xlog/ — Adapters bridging slog to cron logger interface.
• generator/ — ID generators (RandomInt64ID).

4. Adapters Layer (internal/kurious/adapters/)

Concrete implementations of domain interfaces:

• sqlite_*_repository.go — SQLite-backed implementations using sqlx named queries. Each defines a row type with AsDomain() for entity mapping.
• sqlite_connection.go — Connection factory; applies embedded migrations, returns ready-to-use repository instances.
• memory_mapper.go — In-memory CourseMapper implementation; loads dictionary counts from the course repository, maps IDs ↔ names.
• not_implemented.go — Sentinel adapter types returning ErrNotImplemented for methods not yet wired up.
• ydb_* — Legacy YDB adapter stubs (engine no longer supported at runtime).

All DB operations create OpenTelemetry spans with db.* semantic attributes.

5. Ports Layer (internal/kurious/ports/)

Delivery mechanisms that drive the application:

• http/ — HTTP server using gorilla/mux. Server struct holds service.Application and delegates to handlers. course.go contains the main List and Index handlers that call query handlers, map results to templ params, and render HTML.
• http/bootstrap/ — Templ (.templ) template files compiled to Go. Defines view parameter structs and HTML rendering.
• background/ — BackgroundProcess wrapping robfig/cron. Registers scheduled handlers like SyncSravniHandler.
• background.go — Cron scheduler with job registration, shutdown, and next-run stats.
• services.go — Services{HTTP, Background} aggregate — the outermost composition point.

6. Service Layer (internal/kurious/service/)

The composition root:

• service.go — NewApplication() selects DB engine, creates connections, builds adapter instances, constructs all command/query handlers (with logging decorators), and assembles the Application struct. Also owns Close() for resource cleanup.

7. Entry Points (cmd/)

Three binaries, each in its own package:

Binary	Location	Purpose
kuriousweb	cmd/kuriweb/	HTTP web server — starts server + optional background process
kuriousbg	cmd/background/	Background sync process — runs cron scheduler only
sravnicli	cmd/dev/sravnicli/	Developer CLI for inspecting sravni.ru data

Each binary reads a JSON config file, constructs service.Application via service.NewApplication, and starts its delivery mechanism.

Structure

.
├── cmd/                                # Entry points
│   ├── kuriweb/                        #   HTTP server binary
│   ├── background/                     #   Background sync binary
│   └── dev/sravnicli/                   #   Developer CLI
│
├── internal/
│   ├── kurious/                        # Application core (hexagon)
│   │   ├── domain/                     #   Entities + repository ports
│   │   │   ├── course.go               #     Course entity
│   │   │   ├── organization.go         #     Organization entity
│   │   │   ├── category.go             #     LearningCategory entity
│   │   │   ├── kurious.go              #     SourceType enum, shared domain types
│   │   │   ├── mapper.go               #     CourseMapper interface
│   │   │   └── repository.go           #     Repository interfaces + params
│   │   │
│   │   ├── app/                        #   Application layer (use cases)
│   │   │   ├── app.go                  #     Application{Commands, Queries}
│   │   │   ├── command/                #     Write-side handlers
│   │   │   │   ├── createcourse.go     #       CreateCourse, CreateCourses
│   │   │   │   ├── createorganization.go
│   │   │   │   ├── deletecourse.go
│   │   │   │   └── updatecoursedescription.go
│   │   │   └── query/                  #     Read-side handlers
│   │   │       ├── getcourse.go
│   │   │       ├── getorganization.go
│   │   │       ├── listcourses.go
│   │   │       ├── listcoursesstats.go
│   │   │       ├── listcoursethematics.go
│   │   │       ├── listlearningtypes.go
│   │   │       ├── listorganizations.go
│   │   │       └── listorganizationstats.go
│   │   │
│   │   ├── adapters/                   #   Repository implementations
│   │   │   ├── sqlite_course_repository.go
│   │   │   ├── sqlite_organization_repository.go
│   │   │   ├── sqlite_learning_category_repository.go
│   │   │   ├── sqlite_connection.go    #     Connection factory + migrations
│   │   │   ├── memory_mapper.go        #     In-memory CourseMapper
│   │   │   ├── not_implemented.go      #     ErrNotImplemented stubs
│   │   │   ├── adapters.go             #     Shared DB helpers, tracing
│   │   │   └── ydb_course_repository.go #   Legacy YDB stub
│   │   │
│   │   ├── ports/                      #   Delivery mechanisms
│   │   │   ├── http/                   #     HTTP server
│   │   │   │   ├── server.go           #       Server, error handling, pagination
│   │   │   │   ├── course.go           #       Course list/index handlers
│   │   │   │   └── bootstrap/          #       Templ templates + params
│   │   │   ├── background/             #     Cron job handlers
│   │   │   │   └── synchandler.go      #       Sravni sync handler
│   │   │   ├── background.go           #     Cron scheduler
│   │   │   └── services.go             #     Services aggregate
│   │   │
│   │   └── service/                    #   Composition root
│   │       └── service.go              #     NewApplication wiring
│   │
│   └── common/                         # Shared infrastructure
│       ├── decorator/                  #   Handler interfaces + logging decorators
│       ├── client/sravni/             #   Sravni.ru HTTP client
│       ├── config/                     #   Config structs
│       ├── errors/                     #   Error types + sentinels
│       ├── generator/                  #   ID generation
│       ├── nullable/                   #   Generic nullable Value[T]
│       ├── xcontext/                   #   Context log helpers
│       ├── xlog/                       #   Logger adapters
│       └── xslices/                    #   Slice utilities
│
├── pkg/xdefault/                        # Public package (WithFallback helper)
├── migrations/sqlite/                  # SQL migrations (go:embed)
├── assets/kurious/static/               # Static assets (go:embed)
├── docs/                                # Documentation
│   └── ARCHITECTURE.md                  #   This file
└── htmlexamples/                        # Templ prototyping

Data Flow

HTTP Request (read path)

HTTP request
  → gorilla/mux router (ports/http/server.go)
    → handler method (ports/http/course.go)
      → parse query params + pagination
        → app.Queries.ListCourses.Handle()     [application layer]
          → decorator: create span, log args    [decorator]
            → courseHandler.Handle()            [application handler]
              → domain.CourseRepository.List() [domain port]
                → sqlite_course_repository      [adapter]
                  → sqlx named query → SQLite   [infrastructure]
          ← domain.ListCoursesResult
      ← result → map to templ params
  ← templ.Render(ctx, w) → HTML response

Background Sync (write path)

cron tick
  → BackgroundProcess scheduler (ports/background.go)
    → syncSravniHandler.Handle()                  [port handler]
      → fill caches (known external IDs, orgs)
      → sravni.Client.GetMainPageState()          [external API]
      → for each learning type:
          → client.ListEducationalProducts()     [rate-limited]
            → deduplicate courses/orgs
        → app.Commands.InsertCourses.Handle()   [application layer]
          → domain.CourseRepository.CreateBatch() [domain port]
            → sqlite_course_repository            [adapter]

Key Design Decisions

1. Pure-Go SQLite (modernc.org/sqlite) — no CGO dependency, builds anywhere.
2. Embedded migrations — SQL files in migrations/sqlite/ are compiled into the binary via go:embed and applied at startup in a transaction.
3. Templ for HTML — type-safe templates compiled to Go; generated _templ.go files are committed to the repo.
4. CGO_ENABLED=0 everywhere — enforced by Taskfile and build flags.
5. Go 1.26 — latest toolchain; see go.mod.
6. OpenTelemetry — spans and metrics on every command/query handler and DB operation; exports to stdout or OTLP (HTTP/gRPC).
7. Single composition root — service.NewApplication is the only place that knows about concrete adapter types. Tests can swap adapters via interfaces.