# 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**](https://www.linkedin.com/in/anagsoares/) 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](https://medium.com/@anagsoares/conhe%C3%A7a-a-roda-%C3%A1gil-um-assessment-para-equipes-de-desenvolvimento-%C3%A1gil-79a7146616b2).

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1755456582992/4dc389da-2218-4178-abc8-19e66353813e.png align="center")

## 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)

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1755456679928/9e92baa3-1844-4c5d-8c74-7c8b24af20f5.png align="center")

## 9\. Want to try it out?

* **Frontend**: [*https://agile-wheel.miguelsmuller.dev.br/*](https://agile-wheel.miguelsmuller.dev.br/)
    
* **Docs**: [*https://agile-wheel-docs.miguelsmuller.dev.br/*](https://agile-wheel-docs.miguelsmuller.dev.br/)
    
* **Code**: [github.com/miguelsmuller/agile-wheel](http://github.com/miguelsmuller/agile-wheel)
    

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