# aws-event-driven-finops-platform

Event-driven AWS banking reference architecture with FinOps, security, and a live frontend.

- URL: https://fernando.moretes.com/open-source/aws-event-driven-finops-platform

- Markdown: https://fernando.moretes.com/open-source/aws-event-driven-finops-platform/guide.md?lang=en

- GitHub: https://github.com/fernandofatech/aws-event-driven-finops-platform

- Homepage: https://finops.moretes.com

- Language: HTML

- Topics: ai, aws, banking, devsecops, event-driven-architecture, eventbridge, finops, kinesis, moretes, msk, portfolio, solution-architecture, sqs, vercel

- Stars: 1

- Forks: 0

- Updated: 2026-05-16T02:23:21Z

---

aws-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](https://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.

### 🏦 Banking Domain

- Event Producer (banking ops) (edge)

### ☁️ AWS Event Mesh

- EventBridge domain routing (messaging)
- SQS buffering & decoupling (messaging)
- Kinesis Data Streams ordered streaming (messaging)
- MSK (Kafka) high-volume workloads (messaging)
- Lambda / Step Functions (compute)
- DynamoDB idempotency & state (storage)
- CloudWatch + X-Ray (security)

### 🔒 Security Pipeline

- GitHub Actions CodeQL · Trivy · Gitleaks (ci)

### 🌐 Frontend

- Vercel finops.moretes.com (frontend)

### Flows

- producer -> eventbridge: domain event
- eventbridge -> sqs: low-volume / decoupled
- eventbridge -> kinesis: ordered stream
- eventbridge -> msk: high-volume Kafka
- sqs -> lambda: trigger
- kinesis -> lambda: stream consumer
- msk -> lambda: Kafka consumer
- lambda -> dynamodb: idempotency check
- lambda -> observability: traces & metrics
- ci -> vercel: deploy on merge

## What makes this architecture worth studying

- Explicit service-selection rationale: each messaging primitive (EventBridge, SQS, Kinesis, MSK) is chosen with documented trade-offs, not picked arbitrarily.
- FinOps as a constraint: cost is treated as an architectural requirement from the start, influencing which service handles which event volume.
- ADR-driven documentation: Architecture Decision Records capture the 'why' behind each significant choice, making the repo useful for learning, not just copying.
- Automated security pipeline: CodeQL, Trivy, Gitleaks, dependency review, and npm audit run on every push via GitHub Actions.
- Live frontend on Vercel: the static site at finops.moretes.com demonstrates the architecture visually and keeps the portfolio accessible without spinning up AWS resources.
- Tested decision logic: the Python layer includes tests for the routing and idempotency logic, so the architecture isn't just a diagram.

## 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., `TransactionAuthorized` sequences 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 -q` gives a compact summary of pass/fail.

3. **Install frontend dependencies and build** — The frontend lives in `frontend/`. `npm ci` ensures a reproducible install from the lockfile. `npm run lint` catches issues before `npm run build` produces the static output.

4. **Review the architecture documentation** — Open `docs/architecture.md` for the ADRs and service-selection rationale. Open `OPERATIONS.md` for 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 in `OPERATIONS.md`. Merges to `main` trigger automatic deploys.

_Full local setup — Python tests and frontend build_

```bash
# 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.md
```

> **Why 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.

## Links

- [GitHub — fernandofatech/aws-event-driven-finops-platform](https://github.com/fernandofatech/aws-event-driven-finops-platform)
- [Live site — finops.moretes.com](https://finops.moretes.com)
- [AWS EventBridge documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html)
- [AWS SQS documentation](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html)
- [Amazon Kinesis Data Streams documentation](https://docs.aws.amazon.com/streams/latest/dev/introduction.html)
- [Amazon MSK documentation](https://docs.aws.amazon.com/msk/latest/developerguide/what-is-msk.html)
- [FinOps Foundation — FinOps Framework](https://www.finops.org/framework/)
- [Author — Fernando Francisco Azevedo](https://fernando.moretes.com)

## Links

- [GitHub repository](https://github.com/fernandofatech/aws-event-driven-finops-platform)
- [Homepage](https://finops.moretes.com)