aws-event-driven-finops-platform
Event-driven AWS banking reference architecture with FinOps, security, and a live frontend.
git clone https://github.com/fernandofatech/aws-event-driven-finops-platform.gitaws-event-driven-finops-platform is a bilingual reference architecture that models a realistic banking event mesh on AWS, deliberately treating cost, security, and observability as first-class architectural constraints alongside the usual functional requirements.
What this repository is and why I built it
Most event-driven demos stop at "publish a message, consume a message." This one goes further. The fictional scenario is a Brazilian banking platform that processes domain events — AccountOpened, PixPaymentRequested, TransactionAuthorized, FraudRiskScored, StatementGenerated — and the architecture has to justify which AWS messaging primitive handles each one and why.
That justification is the point. EventBridge, SQS, Kinesis Data Streams, and MSK are not interchangeable. Each carries a different cost model, ordering guarantee, replay capability, and operational surface. I document those trade-offs explicitly in Architecture Decision Records (ADRs) inside docs/architecture.md, so a reader can follow the reasoning rather than just copy the topology.
The repository also serves as a portfolio artifact. It is bilingual (English and Portuguese), it has a static frontend deployed on Vercel at finops.moretes.com, and it runs a full security pipeline — CodeQL, Trivy, Gitleaks, dependency review, and npm audit — on every push. The goal is to show production-grade discipline on a project that has no production traffic to hide behind.
Architecture overview
Domain events originate from banking operations and are routed through AWS messaging primitives chosen for their specific trade-offs. The static frontend visualises the architecture and is deployed independently on Vercel.
- Event Producer · (banking ops)
- EventBridge · domain routing
- SQS · buffering & decoupling
- Kinesis Data Streams · ordered streaming
- MSK (Kafka) · high-volume workloads
- Lambda / · Step Functions
- DynamoDB · idempotency & state
- CloudWatch · + X-Ray
- GitHub Actions · CodeQL · Trivy · Gitleaks
- Vercel · finops.moretes.com
What makes this architecture worth studying
How the FinOps layer actually works
FinOps in this context is not a dashboard bolted on after the fact. The cost model is embedded in the service-selection logic itself. The core question the architecture answers is: given a banking domain event, which messaging primitive minimises cost while still meeting the event's ordering, durability, and throughput requirements?
- EventBridge handles routing for low-frequency domain events where the per-event pricing is acceptable and the schema registry and filtering capabilities add value.
- SQS absorbs workloads that need buffering and at-least-once delivery but do not require strict ordering — cheaper than Kinesis at low throughput.
- Kinesis Data Streams takes over when ordering within a shard matters (e.g.,
TransactionAuthorizedsequences per account) and throughput justifies the shard-hour cost. - MSK is reserved for high-volume, Kafka-compatible workloads where the operational overhead of a managed Kafka cluster is justified by volume and ecosystem compatibility.
This tiered approach means the architecture scales cost linearly with actual load rather than paying for Kafka-grade infrastructure on every event type. The ADRs in docs/architecture.md quantify the break-even points.
Installing and running locally
- 1
Clone the repository
Clone from GitHub and move into the project root. You will need Python 3.9+ and Node.js 18+ installed.
- 2
Install Python dependencies and run tests
The
-e .flag installs the package in editable mode so the test suite can import the decision logic.pytest -qgives a compact summary of pass/fail. - 3
Install frontend dependencies and build
The frontend lives in
frontend/.npm ciensures a reproducible install from the lockfile.npm run lintcatches issues beforenpm run buildproduces the static output. - 4
Review the architecture documentation
Open
docs/architecture.mdfor the ADRs and service-selection rationale. OpenOPERATIONS.mdfor GitFlow conventions, Vercel deployment secrets, and the security pipeline configuration. - 5
Deploy the frontend to Vercel (optional)
Connect the repository to a Vercel project, set the root directory to
frontend/, and configure the secrets documented inOPERATIONS.md. Merges tomaintrigger automatic deploys.
# Clone
git clone https://github.com/fernandofatech/aws-event-driven-finops-platform.git
cd aws-event-driven-finops-platform
# Python layer — install in editable mode and run tests
python -m pip install -e . pytest
pytest -q
# Frontend layer
cd frontend
npm ci
npm run lint
npm run build
# Review architecture decisions
open docs/architecture.md # or: cat docs/architecture.md
open OPERATIONS.mdWhy the frontend is intentionally static
The frontend/ directory is a dependency-light static site, not a React SPA with a 200-package dependency tree. This is a deliberate FinOps and security decision: zero cold-start latency on Vercel's CDN, a minimal attack surface for the security pipeline to scan, and no runtime cost. The architecture visualisation does not need a backend — it needs to be fast and always available.
Common questions
Does this deploy actual AWS infrastructure?
No. This is a reference architecture and portfolio project. The Python layer contains the decision and routing logic with tests, but there are no IaC templates (CDK, Terraform, CloudFormation) that provision live AWS resources. The value is in the documented trade-offs and the tested logic, not in a one-click deploy.
Why model a banking domain specifically?
Banking events have naturally varied requirements: some need strict ordering (transaction sequences), some need high throughput (fraud scoring at scale), some need reliable at-least-once delivery (statement generation). That variety makes it a useful forcing function for demonstrating why you would not use a single messaging primitive for everything.
What is the purpose of the DynamoDB table?
Idempotency and event state. In an at-least-once delivery model, consumers must be able to detect and safely discard duplicate events. DynamoDB's conditional writes make it a practical idempotency store — the architecture documents the key schema and TTL strategy used.
Can I contribute or adapt this for my own portfolio?
The repository is public. Contribution guidance and GitFlow conventions are in OPERATIONS.md. If you adapt it, I ask that you document your own trade-off reasoning rather than copying the ADRs verbatim — the reasoning is the portfolio artifact, not the topology.
Who this is for and when to use it
This repository is useful in three situations. First, if you are an engineer evaluating AWS messaging primitives for a real project and want a worked example with documented trade-offs rather than a vendor comparison table. Second, if you are a hiring manager or technical interviewer assessing how a solutions architect thinks about cost, security, and observability as architectural constraints — the ADRs and test suite are the evidence. Third, if you are building your own architecture portfolio and want a structural template that goes beyond diagrams: bilingual documentation, a security pipeline, a live frontend, and tested logic in the same repository.
It is not a production-ready deployment kit. There are no IaC templates, no environment-specific configuration management, and no operational runbooks beyond what is in OPERATIONS.md. Treat it as a detailed reference and a thinking tool, not as infrastructure you can fork and deploy unchanged.