Agile Wheel — Behind the Scenes of an Implementation from Scratch to Deployment

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:

1. Hexagonal – testable, isolated domain, independent of infrastructure.

2. Realtime first – collective results without page reloads.

3. Observable quality – coverage, alerts in Sentry, and Sonar analysis.

4. Automated CI/CD – GitHub Actions deploying to Cloud Run and Vercel.

5. Living documentation – useful, close to the code, and always up to date.

3. Stack (and why)

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

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?

• Frontend: https://agile-wheel.miguelsmuller.dev.br/

• Docs: https://agile-wheel-docs.miguelsmuller.dev.br/

• Code: github.com/miguelsmuller/agile-wheel

Contributions, PRs, or even a ⭐ are more than welcome!