A report on how I turned the agile assessment framework by Ana G. Soares into a full-stack application, now with more than 250 commits and a continuous delivery pipeline.
1. Motivation and first steps
I first came across the Agile Wheel Framework during my Software Engineering postgraduate studies at PUC-Minas. The combination of four dimensions × five principles and the radar visualization, applied in a collective dynamic, caught my attention for its simplicity and objectivity.
If you are not familiar with it yet, I recommend this introductory article: Agile Wheel: An assessment to measure your agile team’s maturity.
I then decided to build a practical implementation, with two main goals:
apply hexagonal architecture (ports & adapters), an approach I value and try to use whenever possible;
deliver a realtime experience with WebSockets, exploring a long-standing interest I had not yet taken into production.
The initial goal was to have something usable before the end of the semester. From there, the project evolved with CI/CD, documentation, and deployment. Even before making the repository public, I received a spontaneous contribution offer for UI/UX improvements in a GitHub issue — an encouraging sign that the idea could attract collaboration.
2. Goals that guided the project
The project was driven by a few simple yet firm principles:
Hexagonal – testable, isolated domain, independent of infrastructure.
Realtime first – collective results without page reloads.
Observable quality – coverage, alerts in Sentry, and Sonar analysis.
Automated CI/CD – GitHub Actions deploying to Cloud Run and Vercel.
Living documentation – useful, close to the code, and always up to date.
3. Stack (and why)
| Layer | Tech | Rationale |
| Frontend | Angular 17 + NgRx | Mature ecosystem and strong type-safety support. |
| Backend | FastAPI (Python) | Productivity and fast prototyping. |
| Realtime | Native WebSockets in FastAPI | Less coupling and direct protocol control. |
| Database | MongoDB / Firestore | Easy local use and natural fit for GCP. |
| Infra | Cloud Run (back) · Vercel (front) | Simple deploy, automatic SSL, and pay-as-you-go. |
| Observability | Sentry + SonarCloud | Error monitoring and measurable quality. |
| CI | GitHub Actions | Unified pipeline validating frontend and backend. |
4. Architecture in practice
(Diagram in progress — the idea is to separate frontend/backend and show HTTP/WS flows).
Backend (FastAPI)
Ports/Adapters: expose only serializable contracts, via HTTP and WebSockets.
Use Cases: orchestrate business rules, independent of DB or protocol.
Repositories: implementations for MongoDB (dev) and Firestore (prod), plugged through interfaces.
Frontend (Angular)
NgRx for state management, isolating side effects and making testing easier.
HTTP + WS services act as the “ports” of the frontend, communicating with the backend without knowing internal details.
This separation kept tests fast and coverage high on both sides.
5. DevOps & Quality
The project has already surpassed 250 commits, following the small, safe steps philosophy.
CI workflows: lint → test → security scan → build → deploy.
Sonar Gates: block merges if coverage decreases or new code smells appear.
Sentry: currently integrated into the backend, with plans to expand to the frontend.
The result has been a short feedback loop and consistent deployments.
6. How much does it cost? R$ 0,00
The entire infrastructure runs on free plans:
Vercel (frontend): free plan with automatic builds and global CDN.
GCP Cloud Run (backend): free tier covers the current traffic needs.
Firestore: usage stays within the free quota (minimal reads/writes).
SonarCloud and Sentry: free/open-source plans that fit the project.
Proof that it is possible to experiment with a well-structured architecture without spending a cent — you just need discipline to stay within the quotas.
7. Challenges & learnings
| Challenge | What I learned / next steps |
| Scaling WebSockets on Cloud Run | Many simultaneous connections can become a bottleneck — still under study. |
| Synchronizing room state | Adopted diffs and RxJS on the frontend to reduce payload and improve UX. |
| Hexagonal ≠ silver bullet | Too many ports lead to boilerplate; created helpers for easier DTO mapping. |
8. Roadmap – Next steps
New interface – updated design system, accessibility, and dark mode.
Frontend toasts – temporary messages integrated into the design system.
Better participant and realtime status display
Show online/offline users and voting status.
Add status field in the user object (online, offline, voted, not_voted).
Updates via WebSocket or DB + reactive polling.
Radar chart – improve scalability, responsiveness, and readability.
Switch localStorage to sessionStorage – map current use cases, test UX impact, and apply if feasible.
Distributed tracing – end-to-end tracing (frontend + backend) to close the observability loop.
Infrastructure as Code (IaC) – version and reproduce infra with Terraform.
9. Want to try it out?
Contributions, PRs, or even a ⭐ are more than welcome!
