Green-Scale Event Ledger: an Event-Driven Backend with Go and SQS

Green-Scale Event Ledger is a demonstration project that explores the incremental construction of an event-driven backend. It connects an HTTP gateway written in Go to a local SQS queue, a TypeScript worker for event validation, and an initial PostgreSQL persistence layer.

The project runs locally: Docker Compose starts LocalStack, PostgreSQL with pgvector, and Redis. It is neither a commercial product nor a hosted service, and it does not require an AWS account.

The problem being explored

In asynchronous systems, accepting a request does not mean that processing has finished. The project makes several stages—often hidden behind a single API—observable and verifiable:

• receiving and initially checking the HTTP request;
• sending the message to a queue;
• reading it and validating its contract at runtime;
• handling redelivery and idempotent persistence;
• separating temporary failures, invalid events, and application conflicts.

Current architecture

HTTP client → Go gateway → local SQS → TypeScript worker → Zod validation

TypeScript → PostgreSQL

The gateway returns 202 Accepted only after the queue confirms receipt. This response means that SQS has accepted the message; it does not mean that the event has already been validated or stored.

Available components

• Go gateway: exposes POST /events, checks the JSON format, size, and content type, and sends the body to SQS.
• Local infrastructure: Docker Compose configures LocalStack, the main queue, a dead-letter queue, PostgreSQL, and Redis.
• TypeScript contract: Zod validates the UUID, UTC timestamp, event type, source, metadata, and payload.
• SQS consumer: performs long polling, JSON parsing, and validation of the received message.
• Initial persistence: PostgreSQL stores the complete event as JSONB; the repository distinguishes a new insert, an identical redelivery, and conflicting content for the same identifier.

Technical decisions

Separated responsibilities

The gateway applies transport-level checks only. Contract validation belongs to the worker, keeping HTTP acceptance separate from application processing.

Explicit idempotency

eventId is the primary key. A redelivery with the same ID and content is recognised, while the same ID associated with different data raises a conflict without overwriting the original event.

Reproducible infrastructure

LocalStack makes it possible to experiment with SQS without using real cloud resources. The credentials in the examples are placeholders limited to the local environment.

Documented verification

The repository records the checks already completed and the commands used. They include:

• Go gateway tests and race detection;
• a real HTTP submission to the LocalStack queue;
• rejection of malformed JSON and handling of an unreachable SQS endpoint;
• TypeScript static checks and build;
• receipt of valid and non-conforming events;
• PostgreSQL connectivity and sequential idempotent storage;
• rejection of a conflict without changing the original content.

This evidence comes from the project's public documentation. The repository has not been installed or executed on the matcode.dev production server.

Current limitations

This page deliberately separates working components from planned work:

• SQS consumption is not yet connected to PostgreSQL persistence;
• valid messages are not yet deleted from the queue;
• the complete dead-letter queue path still needs to be verified;
• Redis and vector search are not yet used by the application code;
• automated worker tests, benchmarks, and a CI pipeline are not yet available;
• concurrent redelivery has not yet been tested.

How to examine the project

The README provides prerequisites, Docker Compose commands, gateway startup instructions, HTTP examples, the worker build process, and PostgreSQL checks. Some steps modify the local database and should be run only in the development environment described by the repository.

What the project demonstrates

Green-Scale documents an applied learning path covering API design, asynchronous messaging, runtime contracts, idempotency, and a clear distinction between verified components and future work. Its value is not a supposedly “finished” demo, but the traceability of its decisions and limitations.

View the repository on GitHub or return to the collection of recent projects. If your team works on backends, APIs, or asynchronous integrations, you can contact me.