# Serverside Architecture Selector

> Defines the system architecture with a focus on simplicity, scalability, and separation of concerns.

- Skill: `lucas-martino/serverside-architecture-selector` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lucas-martino/serverside-architecture-selector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucas-martino/serverside-architecture-selector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lucas-martino (https://skillmd.com/u/lucas-martino)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lucas-martino/serverside-architecture-selector

---


## Golden Principle: "The Last Responsible Moment"
* **Simplicity is King:** Always prefer the simplest solution that meets current requirements.
* **Domain First:** Do not make infrastructure decisions before defining domain requirements.
* **Coupling vs. Abstraction:** Favor simple coupling over premature abstraction until a pattern of repetition is proven.

---

## 1. Pre-flight Check

* **Domain vs. Effort:** If the domain complexity is High/Extreme, the agent MUST propose a draft of Bounded Contexts and require validation before suggesting any code patterns.
* **Persistence and Performance:** CQRS must not be suggested without a clear justification regarding "read/write mismatch".
* **Legacy and ACL:** If there is integration with legacy systems, an **Anti-Corruption Layer (ACL)** must be designed obligatorily.
* **Microservices:** Do not suggest microservices unless the cost of Team Cognitive Load or the need for independent scaling is the main bottleneck.

---

## 2. Architecture Definition (Decision Tree)

### **A: What is the complexity of your Business Domain?**
* **Low (MVP/CRUD):** Transaction Script / MVC (Focus on simplicity and fast delivery).
* **Medium (Clear rules, many integrations):** Hexagonal Architecture (Side-effects isolation and testability).
* **High (Complex domain, low change rate):** Clean Architecture (Full framework abstraction and UI independence).
* **Extreme (Complex, mutable, core-to-business domain):** Domain-Driven Design (Ubiquitous Language, Bounded Contexts, and Living Business Logic).

### **B: What is the complexity of data access?**
* **Simple access (Simple CRUD, single database):** Repository Pattern.
* **Complex transactions (Complex transactions, multiple tables):** Repository Pattern + Unit of Work.
* **Read-Intensive / Audit (Complex domain, read-intensive, or audit trails):** Data Mapper + CQRS (Command Query Responsibility Segregation).

### **C: What is the Communication and State strategy?**
* **Synchronous (Strong Coupling):** Request-Response (Focus on immediate consistency).
* **Asynchronous (Event-Driven):** Pub/Sub or Message Queuing (Focus on decoupling and resilience).
* **Distributed State / Auditing:** Event Sourcing (The state is the sum of all past events).

### **D: What is the scale of the operation?**
* **Fast growth/Uncertain boundaries:** Modular Monolith (Low infrastructure cost and easier refactoring).
* **Massive scale/Independent teams:** Microservices (Independência de deploy, poliglotismo, High scalability and tolerance for cost/complexity).

### **E: Who are the consumers?**
* **Public API / Multiple platforms:** REST.
* **Complex data needs / Multiple frontends:** GraphQL.
* **Real-time / Continuous data flow:** WebSockets / Server-Sent Events.
* **Internal microservices (Inter-service):**
    - **Low Latency / Performance:** gRPC.
    - **Simplicity / Universality:** REST.

### **F: Evolution and Lifecycle Stage**
* **Initial Stage (Speed & Low overhead):** Modular Monolith (Logical boundaries, shared database, simplified deployment).
* **Growth Stage (Scaling specific modules or independent team growth):** Extract Bounded Context to Microservice (Physical decoupling only when scaling needs differ).
* **Optimization Stage (Highly granular, event-driven tasks):** Serverless Functions / FaaS (Focused on side-effects and ephemeral workloads only).

### **G: Mobile & Multi-client Strategy (BFF Validation)**
* **Direct Integration:** Use when the frontend is a single Web App and the API already returns optimized payloads.
* **Backend For Frontend (BFF):** **MANDATORY** if one or more of the following conditions are met:s
    1. **Over-fetching/Latency:** Mobile clients on 3G/4G receiving large JSONs where only 10% of fields are used.
    2. **API Orchestration:** The frontend needs to call 3+ microservices to render a single screen (Chatty I/O).
    3. **Protocol Translation:** Frontend needs REST/WebSockets, but downstream services use gRPC or SOAP.
    4. **Client-Specific Logic:** Mobile requires different data shapes, specific push notification logic, or image resizing not needed by Web.
* **BFF Rejection Criteria (When NOT to use)**
    1. **Passthrough Proxy:** If the BFF only forwards requests 1:1 to a single downstream service without transformation.
    2. **Shared BFF:** If you are building a "Universal BFF" for Web, iOS, and Android (this is just another API Gateway).
    3. **Business Logic Leakage:** If you find yourself implementing domain rules (discounts, taxes, auth-logic) in the BFF. These belong in the Domain/Microservice.

---

## 3. Review Checklist
* [ ] Does the architecture match the team size and cognitive load capacity?
* [ ] Is the BFF justified by specific UI needs or network constraints?
* [ ] Are there clear boundaries (Bounded Contexts) even in a Modular Monolith?
* [ ] Is the "Dependency Rule" pointing towards the Domain in all suggested layers?