{"id":35214558,"url":"https://github.com/copyleftdev/synapse-spec-first","last_synced_at":"2026-05-07T06:38:50.581Z","repository":{"id":330543918,"uuid":"1123101577","full_name":"copyleftdev/synapse-spec-first","owner":"copyleftdev","description":"Doc-First Event Processing: A demonstration of specification-driven development with Go, OpenAPI, AsyncAPI, and Testcontainers","archived":false,"fork":false,"pushed_at":"2025-12-26T07:49:27.000Z","size":2493,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-07T09:14:30.722Z","etag":null,"topics":["api-design","api-first","asyncapi","code-generation","conformance-testing","contract-testing","developer-experience","docker","documentation-first","event-driven","go","golang","integration-testing","microservices","nats","openapi","spec-first","specification-driven","testcontainers","watermill"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/copyleftdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-26T07:25:32.000Z","updated_at":"2025-12-27T12:52:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/copyleftdev/synapse-spec-first","commit_stats":null,"previous_names":["copyleftdev/synapse-spec-first"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/copyleftdev/synapse-spec-first","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fsynapse-spec-first","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fsynapse-spec-first/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fsynapse-spec-first/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fsynapse-spec-first/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/copyleftdev","download_url":"https://codeload.github.com/copyleftdev/synapse-spec-first/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fsynapse-spec-first/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32726553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-design","api-first","asyncapi","code-generation","conformance-testing","contract-testing","developer-experience","docker","documentation-first","event-driven","go","golang","integration-testing","microservices","nats","openapi","spec-first","specification-driven","testcontainers","watermill"],"created_at":"2025-12-29T21:20:46.364Z","updated_at":"2026-05-07T06:38:50.576Z","avatar_url":"https://github.com/copyleftdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/logo.png\" alt=\"Synapse Mascot\" width=\"400\"\u003e\n\u003c/p\u003e\n\n# Synapse: Doc-First Event Processing\n\n\u003e *\"We're software engineers. We create worlds. Why wouldn't we try to make them perfect?\"*\n\nA complete demonstration of **specification-driven development** using Go, showcasing how to build event-driven systems where the spec is the single source of truth.\n\n![Architecture](scripts/output/architecture.png)\n\n## What Is This?\n\nThis project demonstrates a **doc-first development workflow**:\n\n1. **Write specifications first** (OpenAPI 3.1 + AsyncAPI 3.0)\n2. **Generate code from specs** (custom `synctl` generator)\n3. **Implement to interfaces** (handlers, pipeline stages)\n4. **Validate with conformance tests** (responses must match specs)\n\n## Quick Start\n\n```bash\n# Clone the repo\ngit clone https://github.com/copyleftdev/synapse-spec-first.git\ncd synapse-spec-first\n\n# One-time setup (downloads deps + generates code)\nmake setup\n\n# Run all tests\nmake test\n\n# Start the server\nmake run\n```\n\n## Makefile Commands\n\nThis project includes a comprehensive Makefile for a pleasant developer experience:\n\n```bash\nmake help              # Show all available targets\n```\n\n### 🚀 Quick Commands\n\n| Command | Description |\n|---------|-------------|\n| `make setup` | One-time setup for new clones |\n| `make generate` | Regenerate code from specs |\n| `make test` | Run all tests (requires Docker) |\n| `make test-short` | Run fast tests (no Docker) |\n| `make run` | Start the server |\n\n### 🧪 Testing\n\n| Command | Description |\n|---------|-------------|\n| `make test-conformance` | Run OpenAPI/AsyncAPI conformance tests |\n| `make test-pipeline` | Run pipeline integration tests |\n| `make coverage` | Generate coverage report |\n| `make benchmark` | Run benchmarks |\n\n### 🔧 Development\n\n| Command | Description |\n|---------|-------------|\n| `make lint` | Format and vet code |\n| `make build` | Build the synapse binary |\n| `make diagrams` | Generate architecture diagrams |\n| `make validate-specs` | Validate OpenAPI/AsyncAPI specs |\n| `make clean` | Remove build artifacts |\n\n### 🔄 Workflow Shortcuts\n\n| Command | Description |\n|---------|-------------|\n| `make dev` | generate → test-short → run |\n| `make ci` | deps → generate → lint → test |\n| `make all` | Full build pipeline |\n\n## The Philosophy\n\n![Doc-First Lifecycle](scripts/output/doc_first_lifecycle.png)\n\nTraditional development: *Write code → Document later (maybe)*\n\nDoc-first development: *Write spec → Generate code → Implement → Prove conformance*\n\nRead the full article: **[ARTICLE.md](ARTICLE.md)**\n\n## Architecture\n\n### System Overview\n\n![Pipeline Stages](scripts/output/pipeline_stages.png)\n\n- **API Layer**: Chi router with generated interfaces\n- **Event Bus**: NATS JetStream via Watermill\n- **Pipeline**: Validate → Enrich → Route stages\n- **Storage**: PostgreSQL for persistence, Redis for caching\n- **Testing**: Testcontainers for real infrastructure\n\n### Project Structure\n\n```\nsynapse/\n├── asyncapi/              # AsyncAPI 3.0 event specifications\n├── openapi/               # OpenAPI 3.1 REST specifications\n├── cmd/\n│   ├── synapse/           # Application entry point\n│   └── synctl/            # Custom code generator\n├── internal/\n│   ├── generated/         # Generated from specs\n│   ├── handler/           # HTTP handlers\n│   ├── pipeline/          # Watermill event pipeline\n│   ├── conformance/       # Contract testing\n│   └── testutil/          # Testcontainers helpers\n└── scripts/               # Diagram generation\n```\n\n## Testing Strategy\n\n![Testing Strategy](scripts/output/testing_strategy.png)\n\n### Conformance Testing\n\n```go\n// Validate HTTP responses against OpenAPI schema\nresult := suite.RunTest(ctx, client, baseURL,\n    \"GET\", \"/health\",\n    nil,\n    http.StatusOK,\n    \"HealthResponse\",  // Must match this schema\n)\n\n// Validate events against AsyncAPI schema\nresult := suite.ValidateEvent(\n    \"orders/ingest\",\n    \"OrderReceivedPayload\",\n    orderJSON,\n)\n```\n\n### Running Tests\n\n```bash\n# Unit tests (fast)\ngo test ./... -short\n\n# Integration tests (requires Docker)\ngo test ./... -v\n\n# Conformance tests only\ngo test ./internal/conformance/... -v\n```\n\n## Code Generation\n\nThe custom `synctl` generator creates:\n\n| File | Contents |\n|------|----------|\n| `types.gen.go` | 31 Go structs from OpenAPI + AsyncAPI schemas |\n| `server.gen.go` | HTTP interface with all endpoint methods |\n| `client.gen.go` | Typed HTTP client with auth |\n| `events.gen.go` | Watermill publishers + handlers |\n\n```bash\n# Regenerate after spec changes\ngo run ./cmd/synctl\n```\n\n## Diagrams\n\nGenerated using Python's [diagrams](https://diagrams.mingrammer.com/) library:\n\n```bash\ncd scripts\n./venv/bin/python generate_all.py\n```\n\n| Diagram | Description |\n|---------|-------------|\n| [architecture.png](scripts/output/architecture.png) | System architecture |\n| [doc_first_lifecycle.png](scripts/output/doc_first_lifecycle.png) | Development workflow |\n| [pipeline_stages.png](scripts/output/pipeline_stages.png) | Event processing |\n| [testing_strategy.png](scripts/output/testing_strategy.png) | Testing approach |\n| [philosophy.png](scripts/output/philosophy.png) | Core principles |\n\n## Technology Stack\n\n- **Go 1.21+** — Application language\n- **Chi** — HTTP router\n- **Watermill** — Event-driven processing\n- **NATS** — Message broker\n- **PostgreSQL** — Persistence\n- **Redis** — Caching\n- **Testcontainers** — Integration testing\n- **OpenAPI 3.1** — REST API specification\n- **AsyncAPI 3.0** — Event specification\n\n## Acknowledgments\n\n- **OpenAPI Initiative** — REST API specification standard\n- **AsyncAPI Initiative** — Event-driven API specification\n- **Testcontainers** — Real infrastructure in tests\n- **Three Dots Labs** — Watermill event library\n- **NATS.io** — High-performance messaging\n\n## License\n\n[![CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)\n\nThis work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).\n\n---\n\n*Built to demonstrate that \"the perfect world\" is the one we choose to create.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fsynapse-spec-first","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcopyleftdev%2Fsynapse-spec-first","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fsynapse-spec-first/lists"}