architect

仓库: htlin222/dotfiles
安装量: 34
排名: #19947

安装

npx skills add https://github.com/thebushidocollective/han --skill architect
Architecture Design
Design system architecture and make strategic technical decisions.
Core Principle
Good architecture enables change while maintaining simplicity.
Name
han-core:architect - Design system architecture and high-level technical strategy
Synopsis
/architect [arguments]
Architecture vs Planning
Architecture Design (this skill):
Strategic: "How should the system be structured?"
Component interactions and boundaries
Technology and pattern choices
Long-term implications
System-level decisions
Technical Planning:
Tactical: "How do I implement feature X?"
Specific implementation tasks
Execution details
Short-term focus
Use /architect when:
Designing new systems or subsystems
Significant system change (new subsystem, major refactor)
Affects multiple components or teams
Major refactors affecting multiple components
Technology selection decisions
Defining system boundaries and interfaces
Long-term technical strategy needed
Need to evaluate multiple approaches
Decisions have broad impact
Use /plan when:
Implementing within existing architecture
Implementing specific feature within existing architecture
Tactical execution planning
Breaking down known work
Architecture is already decided
Task sequencing and execution
Architecture Process
1. Understand Context
Business context:
What problem are we solving?
Who are the users?
What are the business goals?
What are the success metrics?
Technical context:
What exists today?
What constraints exist?
What must we integrate with?
What scale must we support?
Team context:
What's our expertise?
What can we maintain?
What's our velocity?
2. Gather Requirements
Functional requirements:
What must the system do?
What are the features?
What are the user scenarios?
Non-functional requirements:
Performance
Response time, throughput
Scalability
Expected load, growth
Availability
Uptime requirements
Security
Compliance, data protection
Maintainability
Team size, skills
Cost
Budget constraints Example:

Requirements

Functional

Users can search products by name/category

Users can add items to cart

Users can checkout and pay

Non-Functional

Search response time < 200ms (p95)

Support 10,000 concurrent users

99.9% uptime

PCI DSS compliant for payments

Team of 5 developers can maintain 3. Identify Constraints Technical constraints: Must use existing authentication system Must integrate with legacy inventory system Database must be PostgreSQL (existing infrastructure) Business constraints: Budget for infrastructure Must support EU data residency Team constraints: Team experienced in Python, less in Go No DevOps specialist on team Remote team across timezones 4. Consider Alternatives Never design in a vacuum - consider options: Example: Data storage choice Option 1: PostgreSQL Pros: Team knows it, ACID guarantees, rich query support Cons: Vertical scaling limits, setup complexity Option 2: MongoDB Pros: Flexible schema, horizontal scaling Cons: Team unfamiliar, eventual consistency Option 3: DynamoDB Pros: Fully managed, auto-scaling Cons: Vendor lock-in, query limitations, cost at scale Decision: PostgreSQL Team expertise outweighs scaling concerns Can re-evaluate if scale becomes issue Faster initial development 5. Design System Structure Define components and their responsibilities: ┌─────────────────────────────────────────────┐ │ Client Apps │ │ (Web, iOS, Android) │ └────────────────┬────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ API Gateway / Load Balancer │ └────────────────┬────────────────────────────┘ │ ┌────────┴────────┐ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ Auth │ │ Core API │ │ Service │ │ Service │ └───────┬───────┘ └───────┬───────┘ │ │ │ ┌────────┴────────┐ │ ▼ ▼ │ ┌──────────────┐ ┌──────────────┐ │ │ PostgreSQL │ │ Redis │ │ │ (Primary) │ │ (Cache) │ │ └──────────────┘ └──────────────┘ │ ▼ ┌───────────────┐ │ User DB │ └───────────────┘ Component descriptions:

Components

API Gateway ** Responsibility: ** Route requests, rate limiting, authentication ** Technology: ** Nginx ** Dependencies: ** Auth Service, Core API Service ** Scale: ** 2-3 instances behind load balancer

Auth Service ** Responsibility: ** User authentication, session management, JWT issuing ** Technology: ** Python (Flask), PostgreSQL ** API: ** REST ** Scale: ** Stateless, 2-N instances

Core API Service ** Responsibility: ** Business logic, data access, external integrations ** Technology: ** Python (FastAPI), PostgreSQL, Redis ** API: ** REST ** Scale: ** Stateless, 2-N instances

PostgreSQL ** Responsibility: ** Primary data store ** Scale: ** Primary with read replica

Redis ** Responsibility: ** Session storage, caching, rate limiting ** Scale: ** Cluster mode (3 nodes) 6. Define Interfaces API contracts:

API Design

POST /api/auth/login ** Purpose: ** Authenticate user, issue JWT ** Request: ** ```json { "email": "user@example.com", "password": "secure_password" } Response (200): { "token" : "eyJ..." , "user" : { "id" : "123" , "email" : "user@example.com" , "name" : "John Doe" } } Errors: 400: Invalid request 401: Invalid credentials 429: Rate limit exceeded

7. Plan for Failure

What can go wrong? - Database unavailable - External API down - Network partition - High load - Data corruption Mitigation strategies: - Retry with exponential backoff - Circuit breakers for external services - Graceful degradation - Health checks and monitoring - Database backups Example: ```markdown

Failure Scenarios

Database Unavailable

Impact: Cannot read/write data Mitigation: - Read replica failover (automated) - Circuit breaker after 3 failures - Cache serves stale data for 5 minutes - User sees degraded experience message Recovery: Manual failover to replica, fix primary

External Payment API Down

Impact: Cannot process payments Mitigation: - Retry 3 times with exponential backoff - Queue payments for later processing - User notified of delay - Alert on-call engineer Recovery: Process queued payments once API recovers 8. Document Decisions Architecture Decision Record (ADR):

ADR-001: Use PostgreSQL for Primary Database ** Status: ** Accepted ** Date: ** 2024-01-15 ** Deciders: ** Tech Lead, Backend Team

Context We need to choose a primary database for user data, products, and orders. Requirements: - Strong consistency (ACID) - Complex queries (joins, aggregations) - < 200ms query time for 90% of queries - Support 100k users initially

Decision Use PostgreSQL as primary database.

Alternatives Considered

MongoDB

** Pros: ** Flexible schema, horizontal scaling - ** Cons: ** Team unfamiliar, eventual consistency issues - ** Why not: ** Team expertise more valuable than flexibility

DynamoDB

** Pros: ** Managed service, auto-scaling - ** Cons: ** Vendor lock-in, limited query capability, cost - ** Why not: ** Query limitations would hurt development velocity

MySQL

** Pros: ** Similar to PostgreSQL, team knows it - ** Cons: ** Less feature-rich than PostgreSQL - ** Why not: ** PostgreSQL offers JSON support, better full-text search

Consequences ** Positive: ** - Team can be productive immediately - Strong consistency guarantees - Rich query capabilities - JSON support for flexible data ** Negative: ** - Vertical scaling limits (mitigated: can add read replicas) - More complex than managed services (mitigated: use RDS) - Higher operational overhead ** Trade-offs: ** - Chose familiarity over horizontal scaling - Chose rich queries over eventual consistency - Can re-evaluate if scale requirements change

Validation

Team confirmed expertise in PostgreSQL

Load testing shows meets performance requirements

Cost analysis shows acceptable for first year Architecture Document Structure

Architecture Design: [System/Feature Name]

Context

Problem Statement [What business problem are we solving?]

Goals [What are we trying to achieve?]

Non-Goals [What are we explicitly NOT trying to achieve?]

Requirements ** Functional: ** - [Requirement 1] - [Requirement 2] ** Non-Functional: ** - Performance: [e.g., < 200ms response time] - Scalability: [e.g., handle 10k concurrent users] - Security: [e.g., PCI compliance] - Maintainability: [e.g., easy to modify]

Constraints [Technical, time, resource, or business constraints]

Current Architecture [What exists today? What needs to change?]

Proposed Architecture

High-Level Design [Diagram or description of system components] ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ Client │────▶│ API │────▶│ Database │ └─────────────┘ └─────────────┘ └──────────────┘ │ ▼ ┌─────────────┐ │ Cache │ └─────────────┘

Components

Component A

Responsibility: [What it does] Interface: [How others interact with it] Dependencies: [What it depends on] Technology: [Implementation stack]

Component B

[Similar structure...]

Data Flow

[How data moves through the system]

API Design

[Key endpoints, schemas, contracts]

Data Model

[Database schema, key entities]

Security Model

[Authentication, authorization, data protection]

Alternative Approaches Considered

Alternative 1: [Approach name]

Pros: - [Advantage 1] - [Advantage 2] Cons: - [Disadvantage 1] - [Disadvantage 2] Why not chosen: [Reasoning]

Alternative 2: [Another approach]

[Similar structure...]

Decision Rationale

Why This Architecture?

[Explain the key decisions and trade-offs]

Trade-offs Accepted

[What we gave up for what benefits]

Assumptions

[What we're assuming to be true]

Implementation Strategy

Phase 1: [Foundation]

[What to build first]

Phase 2: [Core Features]

[Next phase]

Phase 3: [Enhancement]

[Final phase]

Migration Strategy

[If replacing existing system, how to transition?]

Risks & Mitigation

Risk Impact Probability Mitigation
[Risk 1] High Medium [How to mitigate]
[Risk 2] Medium Low [How to mitigate]
## Testing Strategy
[How will we validate this architecture?]
## Monitoring & Observability
[How will we know if it's working?]
## Success Metrics
[How will we measure success?]
## Open Questions
[What still needs to be resolved?]
## References
[Links to research, related docs, RFCs]
Architecture Principles
1. Simplicity
Start simple, add complexity only when needed.
BAD: Microservices from day 1 with 20 services
GOOD: Start with monolith, split when needed
Apply YAGNI:
You Aren't Gonna Need It
Don't build for hypothetical future
Add when actually needed
Simpler is easier to maintain
2. Separation of Concerns
Each component has one clear responsibility.
GOOD:
- Auth Service: Authentication only
- User Service: User profile management
- Order Service: Order processing
BAD:
- God Service: Does everything
Apply SOLID principles:
Single Responsibility
Open/Closed
Liskov Substitution
Interface Segregation
Dependency Inversion
3. Loose Coupling
Components depend on interfaces, not implementations.
// BAD: Tight coupling
class
OrderService
{
constructor
(
private
db
:
PostgresDatabase
)
{
}
}
// GOOD: Loose coupling
class
OrderService
{
constructor
(
private
db
:
Database
)
{
}
// Interface
}
Benefits:
Easier to test (mock interface)
Easier to swap implementations
Components can evolve independently
4. High Cohesion
Related functionality stays together.
GOOD:
user/
- create_user.ts
- update_user.ts
- delete_user.ts
- user_repository.ts
BAD:
create/
- create_user.ts
- create_order.ts
update/
- update_user.ts
- update_order.ts
5. Explicit Over Implicit
Make dependencies and contracts clear.
// BAD: Implicit dependency
function
processOrder
(
orderId
:
string
)
{
const
db
=
global
.
database
// Where does this come from?
// ...
}
// GOOD: Explicit dependency
function
processOrder
(
orderId
:
string
,
db
:
Database
,
logger
:
Logger
)
{
// Dependencies are clear
}
6. Fail Fast
Detect and report errors early.
// BAD: Silent failure
function
divide
(
a
:
number
,
b
:
number
)
{
if
(
b
===
0
)
return
0
// Wrong!
return
a
/
b
}
// GOOD: Fail fast
function
divide
(
a
:
number
,
b
:
number
)
{
if
(
b
===
0
)
{
throw
new
Error
(
'Division by zero'
)
}
return
a
/
b
}
7. Design for Testability
Make it easy to test.
// BAD: Hard to test
class
OrderService
{
processOrder
(
orderId
:
string
)
{
const
db
=
new
PostgresDatabase
(
)
// Can't mock
const
api
=
new
PaymentAPI
(
)
// Can't mock
// ...
}
}
// GOOD: Easy to test
class
OrderService
{
constructor
(
private
db
:
Database
,
// Can inject mock
private
api
:
PaymentAPI
// Can inject mock
)
{
}
processOrder
(
orderId
:
string
)
{
// ...
}
}
Common Architecture Patterns
Layered Architecture
┌─────────────────────┐
│ Presentation │ (UI, API controllers)
├─────────────────────┤
│ Business Logic │ (Domain, services)
├─────────────────────┤
│ Data Access │ (Repositories, ORMs)
├─────────────────────┤
│ Database │ (Storage)
└─────────────────────┘
When to use:
Simple to moderate complexity
Hexagonal Architecture (Ports & Adapters)
┌───────────────────────┐
│ External Systems │
│ (UI, DB, APIs) │
└──────────┬────────────┘
│
┌──────────▼────────────┐
│ Adapters │ (Implementation)
│ (REST, PostgreSQL) │
└──────────┬────────────┘
│
┌──────────▼────────────┐
│ Ports │ (Interfaces)
│ (IUserRepo, IAuth) │
└──────────┬────────────┘
│
┌──────────▼────────────┐
│ Core Domain │ (Business logic)
│ (Pure logic) │
└───────────────────────┘
When to use:
Want to isolate business logic, multiple frontends
Microservices
┌─────────┐ ┌─────────┐ ┌─────────┐
│ User │ │ Order │ │ Payment │
│ Service │ │ Service │ │ Service │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
┌───────▼────────┐
│ Message Bus │
│ (Event-driven)│
└────────────────┘
When to use:
Large team, need independent deploy, clear boundaries
Avoid when:
Small team, unclear boundaries, early stage
Event-Driven Architecture
┌─────────┐ ┌─────────────┐ ┌─────────┐
│Producer │──────▶│ Event Bus │──────▶│Consumer │
└─────────┘ └─────────────┘ └─────────┘
When to use:
Async processing, decoupled systems, audit trails
Architectural Patterns to Consider
System Patterns:
Layered architecture
Microservices vs monolith
Event-driven architecture
CQRS (Command Query Responsibility Segregation)
Hexagonal architecture
Data Patterns:
Database per service
Shared database
Event sourcing
CQRS
Cache-aside
Integration Patterns:
API Gateway
Service mesh
Message queue
Pub/sub
GraphQL federation
Anti-Patterns
Premature Optimization
Don't optimize for scale you don't have.
BAD: Build microservices for 100 users
GOOD: Start with monolith, split when needed
Resume-Driven Architecture
Don't choose technology to pad resume.
BAD: "I want to learn Kubernetes, let's use it"
GOOD: "Kubernetes fits our scale needs"
Distributed Monolith
Microservices that are tightly coupled.
BAD: Service A can't deploy without Service B
GOOD: Services are independently deployable
Big Ball of Mud
No structure, everything depends on everything.
BAD: Any code can call any other code
GOOD: Clear layers and boundaries
Analysis Paralysis
Over-analyzing, never shipping.
BAD: Spend months on perfect architecture
GOOD: Design enough to start, iterate
Architecture Review Checklist
Business goals clearly understood
Functional requirements documented
Non-functional requirements defined
Constraints identified
Multiple alternatives considered
Trade-offs explicitly stated
Component responsibilities clear
Interfaces well-defined
Data flow documented
Failure scenarios planned for
Security model defined
Scalability addressed
Testability designed in
Decisions documented (ADRs)
Implementation phases outlined
Team can implement and maintain
Success metrics defined
Examples
When the user says:
"Design the architecture for our multi-tenant system"
"How should we structure our microservices?"
"Plan the technical approach for real-time notifications"
"Design the data model for our marketplace"
"Create architecture for migrating from monolith to services"
Integration with Other Skills
Apply
solid-principles
- Guide component design
Apply
simplicity-principles
- KISS, YAGNI
Apply
orthogonality-principle
- Independent components
Apply
structural-design-principles
- Composition patterns
Use
technical-planning
- For implementation after design
Notes
Use TaskCreate to track architecture design steps
Apply all relevant design principle skills
Create diagrams (ASCII art or reference drawing tools)
Architecture evolves - document decisions and changes
Consider using /plan for detailed implementation after architecture is approved
Archive decisions as ADRs for future reference
Remember
Simplicity first
- Start simple, add complexity when needed
Document decisions
- Future you will thank you
Consider alternatives
- Never the first idea only
State trade-offs
- Every decision has consequences
Design for change
- Systems evolve
The best architecture is the one that's simple enough to ship and flexible enough to evolve.
← 返回排行榜