Monorepo Structure — Wagoe Docs

Wagoe is a monorepo of 33 independently publishable libraries under libs/. Each library can be published to Clojars as a standalone dependency.

Top-level layout

wagoe/
├── src/                   ← Main application source tree
├── libs/                  ← 33 independently publishable libraries
│   ├── core/
│   ├── observability/
│   ├── platform/
│   ├── user/
│   └── ...
├── docs/                  ← Documentation (this site)
├── dev-docs/              ← Internal: ADRs, decisions, presentations
├── resources/conf/        ← Aero-based configuration
│   ├── dev/
│   ├── test/
│   ├── acc/
│   └── prod/
├── deps.edn               ← Root deps with all aliases
└── tests.edn              ← Kaocha test suite definitions

Example applications live under examples/, and CI runs both on every commit:

examples/shop — a generated application: wagoe new plus one scaffolded module, committed as generator output and re-verified by bb example:regen --check
examples/todo — functional core / imperative shell with no framework at all

The former wagoe-examples repository is archived; these two are the examples.

Library structure

Each library under libs/ follows the same pattern:

libs/{library}/
├── src/wagoe/{library}/
│   ├── core/              ← Pure functions
│   ├── shell/             ← Side effects
│   ├── ports.clj          ← Protocol definitions
│   └── schema.clj         ← Malli schemas
├── test/wagoe/{library}/
│   ├── core/              ← Unit tests (^:unit)
│   └── shell/             ← Integration + contract tests
└── AGENTS.md              ← Library-specific dev guide

Library overview

Library Purpose

Library	Purpose
core	Foundation: validation, utilities, interceptor pipeline, feature flags
observability	Logging, metrics, tracing, error reporting (Datadog, Prometheus, OTLP, Sentry)
platform	HTTP, database, CLI infrastructure
ui-style	Shared UI style contract: central CSS/JS bundles and tokens
user	Authentication, authorization, MFA, session management
admin	Auto-generated CRUD admin UI (Hiccup + HTMX)
storage	File storage: local filesystem and S3
scaffolder	Interactive module code generator
cache	Distributed caching: Redis and in-memory
jobs	Background job processing with retry logic
email	Email: SMTP, async, jobs integration
tenant	Multi-tenancy with PostgreSQL schema-per-tenant isolation
realtime	WebSocket / SSE for real-time features
i18n	Internationalisation: marker-based translation, locale chain, EDN catalogues
external	External service adapters: SMTP, IMAP, Twilio, FTPS, SOAP
reports	PDF, CSV, Excel and Word export via the `defreport` macro
calendar	Recurring events, iCal export/import, conflict detection
workflow	Declarative state machine workflows with audit trail
search	Full-text search: PostgreSQL FTS with LIKE fallback
geo	Geocoding (OSM/Google/Mapbox), DB cache, Haversine distance
ai	Framework-aware AI tooling: NL scaffolding, error explainer, test generator
config	Aero config loading and the typed accessors libraries read through
audience	Rule-based audience segmentation: SQL plus predicate evaluation
events	Cross-process event bus: in-memory and Redis Streams
webhooks	Outbound webhooks: signed, retried, per-tenant delivery of bus events
push	Push notifications via FCM and APNs
payments	Payment provider abstraction: Stripe, Mollie, Mock
shared-ui	Shared Hiccup UI primitives: forms, tables, layouts
test	Test kit for apps: test system, Ring client, deterministic jobs and events
devtools	Development only: error pipeline with WGE codes, dev dashboard, REPL helpers
tools	Babashka developer tooling: scaffolding, doctor, quality gates, deploy
wagoe-cli	The `wagoe` command: `wagoe new`, module installer
wagoe-mcp	MCP server for AI coding agents working in a Wagoe project

core

Foundation: validation, utilities, interceptor pipeline, feature flags

observability

Logging, metrics, tracing, error reporting (Datadog, Prometheus, OTLP, Sentry)

platform

HTTP, database, CLI infrastructure

ui-style

Shared UI style contract: central CSS/JS bundles and tokens

user

Authentication, authorization, MFA, session management

admin

Auto-generated CRUD admin UI (Hiccup + HTMX)

storage

File storage: local filesystem and S3

scaffolder

Interactive module code generator

cache

Distributed caching: Redis and in-memory

jobs

Background job processing with retry logic

Email: SMTP, async, jobs integration

tenant

Multi-tenancy with PostgreSQL schema-per-tenant isolation

realtime

WebSocket / SSE for real-time features

i18n

Internationalisation: marker-based translation, locale chain, EDN catalogues

external

External service adapters: SMTP, IMAP, Twilio, FTPS, SOAP

reports

PDF, CSV, Excel and Word export via the defreport macro

calendar

Recurring events, iCal export/import, conflict detection

workflow

Declarative state machine workflows with audit trail

Full-text search: PostgreSQL FTS with LIKE fallback

geo

Geocoding (OSM/Google/Mapbox), DB cache, Haversine distance

Framework-aware AI tooling: NL scaffolding, error explainer, test generator

config

Aero config loading and the typed accessors libraries read through

audience

Rule-based audience segmentation: SQL plus predicate evaluation

events

Cross-process event bus: in-memory and Redis Streams

webhooks

Outbound webhooks: signed, retried, per-tenant delivery of bus events

push

Push notifications via FCM and APNs

payments

Payment provider abstraction: Stripe, Mollie, Mock

shared-ui

Shared Hiccup UI primitives: forms, tables, layouts

test

Test kit for apps: test system, Ring client, deterministic jobs and events

devtools

Development only: error pipeline with WGE codes, dev dashboard, REPL helpers

tools

Babashka developer tooling: scaffolding, doctor, quality gates, deploy

wagoe-cli

The wagoe command: wagoe new, module installer

wagoe-mcp

MCP server for AI coding agents working in a Wagoe project

Running tests per library

clojure -M:test :core
clojure -M:test :user
clojure -M:test:test/pg :admin
# etc.

Configuration

Aero-based configuration with environment profiles in resources/conf/{env}/config.edn. The active environment is controlled by the WAG_ENV environment variable.

export WAG_ENV=dev           # loads resources/conf/dev/config.edn
export WAG_ENV=test          # loads resources/conf/test/config.edn
export WAG_ENV=production    # loads resources/conf/prod/config.edn