"We're software engineers. We create worlds. Why wouldn't we try to make them perfect?"

A complete demonstration of specification-driven development using Go, showcasing how to build event-driven systems where the spec is the single source of truth.

This project demonstrates a doc-first development workflow:

1. Write specifications first (OpenAPI 3.1 + AsyncAPI 3.0)
2. Generate code from specs (custom synctl generator)
3. Implement to interfaces (handlers, pipeline stages)
4. Validate with conformance tests (responses must match specs)

# Clone the repo
git clone https://github.com/copyleftdev/synapse-spec-first.git
cd synapse-spec-first

# One-time setup (downloads deps + generates code)
make setup

# Run all tests
make test

# Start the server
make run

This project includes a comprehensive Makefile for a pleasant developer experience:

make help              # Show all available targets

Traditional development: Write code → Document later (maybe)

Doc-first development: Write spec → Generate code → Implement → Prove conformance

Read the full article: ARTICLE.md

• API Layer: Chi router with generated interfaces
• Event Bus: NATS JetStream via Watermill
• Pipeline: Validate → Enrich → Route stages
• Storage: PostgreSQL for persistence, Redis for caching
• Testing: Testcontainers for real infrastructure

synapse/
├── asyncapi/              # AsyncAPI 3.0 event specifications
├── openapi/               # OpenAPI 3.1 REST specifications
├── cmd/
│   ├── synapse/           # Application entry point
│   └── synctl/            # Custom code generator
├── internal/
│   ├── generated/         # Generated from specs
│   ├── handler/           # HTTP handlers
│   ├── pipeline/          # Watermill event pipeline
│   ├── conformance/       # Contract testing
│   └── testutil/          # Testcontainers helpers
└── scripts/               # Diagram generation

// Validate HTTP responses against OpenAPI schema
result := suite.RunTest(ctx, client, baseURL,
    "GET", "/health",
    nil,
    http.StatusOK,
    "HealthResponse",  // Must match this schema
)

// Validate events against AsyncAPI schema
result := suite.ValidateEvent(
    "orders/ingest",
    "OrderReceivedPayload",
    orderJSON,
)

# Unit tests (fast)
go test ./... -short

# Integration tests (requires Docker)
go test ./... -v

# Conformance tests only
go test ./internal/conformance/... -v

The custom synctl generator creates:

# Regenerate after spec changes
go run ./cmd/synctl

Generated using Python's diagrams library:

cd scripts
./venv/bin/python generate_all.py

• Go 1.21+ — Application language
• Chi — HTTP router
• Watermill — Event-driven processing
• NATS — Message broker
• PostgreSQL — Persistence
• Redis — Caching
• Testcontainers — Integration testing
• OpenAPI 3.1 — REST API specification
• AsyncAPI 3.0 — Event specification

• OpenAPI Initiative — REST API specification standard
• AsyncAPI Initiative — Event-driven API specification
• Testcontainers — Real infrastructure in tests
• Three Dots Labs — Watermill event library
• NATS.io — High-performance messaging

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Built to demonstrate that "the perfect world" is the one we choose to create.