architecture

Guides architecture decisions through requirements analysis, trade-off evaluation, and ADR documentation.

Updated Mar 17, 2026
One-click install
npx skills add https://github.com/beliciobcardoso/mcp-postgres --skill architecture-beliciobcardoso
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture
Source: https://github.com/beliciobcardoso/mcp-postgres/tree/main/.agent/skills/architecture
Command: npx skills add https://github.com/beliciobcardoso/mcp-postgres --skill architecture-beliciobcardoso

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Making software architecture decisions without a structured framework leads to over-engineering, premature complexity, and undocumented rationale that teams later regret. This Skill provides a disciplined decision-making framework that ties every architectural choice to actual requirements and constraints. ## Core Features & Use Cases - Context Discovery: A structured question hierarchy covering scale, team, timeline, domain, and constraints, plus a project classification matrix (MVP, SaaS, Enterprise) to calibrate architecture complexity. - Pattern Selection: Decision trees for data access, domain logic, distributed systems, and API patterns, with red-flag anti-pattern warnings and a simplicity-first principle. - Trade-off Analysis & ADRs: Templates for documenting Architecture Decision Records with options compared, rationale, accepted trade-offs, and revisit triggers. - Use Case: A team starting a new SaaS product uses the classification matrix to determine a modular monolith fits their 5-10 person team, then documents the choice of PostgreSQL and the Repository pattern as ADRs with explicit trade-offs. ## Quick Start Help me decide the architecture for a SaaS application with a 6-person team expecting up to 50K users, and document the key decisions as ADRs.

Frequently Asked Questions about architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between a monolith and microservices architecture?▼

Choose microservices only when you have clear domain boundaries, a team larger than 10 developers, and different scaling needs per service. If any condition is unmet, start with a modular monolith and extract services later when the need is proven.

How to write an Architecture Decision Record (ADR)?▼

An ADR documents the context and problem, the decision made, the rationale tied to requirements, the trade-offs accepted, and the consequences with mitigations. Store ADRs as numbered markdown files such as adr-001-use-nextjs.md under a docs/architecture directory.

When should I use the Repository pattern versus direct ORM access?▼

Use the Repository pattern when you need testability, multiple data sources, or expect the data source to change. For simple CRUD against a single database, direct ORM access with tools like Prisma or Drizzle is simpler and sufficient.

What questions should I ask before designing system architecture?▼

Ask about scale (users, data volume, transaction rate), team size and expertise, timeline pressure, domain complexity, and constraints like budget or legacy integrations. These answers classify the project as MVP, SaaS, or Enterprise and calibrate architecture complexity.

When is event-driven architecture the wrong choice?▼

Event-driven architecture is wrong for simple workflows requiring strong consistency, since it introduces eventual consistency and operational complexity. If you cannot tolerate eventual consistency, use synchronous REST or GraphQL communication instead.