From PACT
Provides C4 diagram templates, architecture patterns, component guidelines, and anti-patterns for PACT Architect phase. Useful for system design, diagrams, boundaries, API contracts, and reviews.
npx claudepluginhub synaptic-labs-ai/pact-plugin --plugin PACTThis skill uses the workspace's default tool permissions.
Design patterns and templates for the Architect phase of PACT. This skill provides
Designs software architectures evaluating monolith/microservices/serverless/event-driven/CQRS/hexagonal patterns; generates C4 diagrams, ADRs, bounded contexts, and quality analysis.
Designs, reviews, and documents complex software architectures using C4 Mermaid diagrams, ADRs, and patterns like Clean, Hexagonal, and DDD for system design reviews.
Guides system design, architecture reviews, ADR creation, hexagonal compliance, Mermaid/PlantUML diagram generation, and layer dependency enforcement.
Share bugs, ideas, or general feedback.
Design patterns and templates for the Architect phase of PACT. This skill provides quick references for architectural decisions and links to detailed pattern implementations.
The C4 model provides four levels of abstraction for system architecture documentation.
Shows your system as a box surrounded by users and other systems it interacts with.
+------------------+
| External User |
+--------+---------+
|
v
+------------------+ +----+----+ +------------------+
| Payment Gateway |<-->| Your |<-->| Email Service |
+------------------+ | System | +------------------+
+---------+
^
|
+--------+---------+
| Admin User |
+------------------+
What to include:
Shows the high-level technical building blocks (not Docker containers).
+----------------------------------------------------------------+
| Your System |
| +----------------+ +----------------+ +--------------+ |
| | Web App | | API | | Database | |
| | (React) |---->| (Node.js) |---->| (Postgres) | |
| +----------------+ +----------------+ +--------------+ |
| | |
| v |
| +----------+ |
| | Cache | |
| | (Redis) | |
| +----------+ |
+----------------------------------------------------------------+
Containers are:
Shows the internal structure of a container.
+---------------------------------------------------------------+
| API Container |
| +-------------+ +-------------+ +-------------------+ |
| | Controllers | | Services | | Repositories | |
| | |--->| |--->| | |
| | UserCtrl | | UserService | | UserRepository | |
| | OrderCtrl | | OrderService| | OrderRepository | |
| +-------------+ +-------------+ +-------------------+ |
| | |
| v |
| +-------------+ |
| | Clients | |
| | PaymentAPI | |
| | EmailClient | |
| +-------------+ |
+---------------------------------------------------------------+
Components are:
For full C4 templates with Mermaid diagrams: See c4-diagram-templates.md
| Principle | Summary | Violation Sign |
|---|---|---|
| Single Responsibility | One reason to change | Class does too many things |
| Open/Closed | Open for extension, closed for modification | Frequent changes to existing code |
| Liskov Substitution | Subtypes replaceable for base types | Override breaks expectations |
| Interface Segregation | Many specific interfaces > one general | Unused interface methods |
| Dependency Inversion | Depend on abstractions | Direct instantiation of dependencies |
Resource Naming:
GET /users # List users
GET /users/123 # Get user
POST /users # Create user
PUT /users/123 # Replace user
PATCH /users/123 # Update user
DELETE /users/123 # Delete user
# Nested resources
GET /users/123/orders
POST /users/123/orders
# Actions (when CRUD doesn't fit)
POST /orders/123/cancel
POST /users/123/verify-email
Pagination:
// Cursor-based (recommended for real-time data)
GET /posts?cursor=abc123&limit=20
// Offset-based (simpler, but has issues with real-time data)
GET /posts?page=2&per_page=20
Error Response Format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
],
"request_id": "req_abc123"
}
}
Repository Pattern:
// Interface
interface UserRepository {
findById(id: string): Promise<User | null>;
findByEmail(email: string): Promise<User | null>;
save(user: User): Promise<User>;
delete(id: string): Promise<void>;
}
// Implementation
class PostgresUserRepository implements UserRepository {
async findById(id: string) {
return this.db.user.findUnique({ where: { id } });
}
// ...
}
Service Layer Pattern:
class UserService {
constructor(
private userRepo: UserRepository,
private emailService: EmailService
) {}
async registerUser(data: CreateUserDto): Promise<User> {
// Business logic
const existingUser = await this.userRepo.findByEmail(data.email);
if (existingUser) {
throw new ConflictError('Email already registered');
}
const user = await this.userRepo.save({
...data,
passwordHash: await hash(data.password)
});
await this.emailService.sendWelcome(user.email);
return user;
}
}
Backend-for-Frontend (BFF):
Mobile App --> Mobile BFF -->
Core Services
Web App --> Web BFF -->
Circuit Breaker:
class CircuitBreaker {
constructor(
private threshold: number = 5,
private timeout: number = 30000
) {
this.failures = 0;
this.state = 'CLOSED';
}
async execute<T>(fn: () => Promise<T>): Promise<T> {
if (this.state === 'OPEN') {
if (Date.now() - this.lastFailure > this.timeout) {
this.state = 'HALF_OPEN';
} else {
throw new Error('Circuit breaker is OPEN');
}
}
try {
const result = await fn();
this.onSuccess();
return result;
} catch (error) {
this.onFailure();
throw error;
}
}
private onSuccess() {
this.failures = 0;
this.state = 'CLOSED';
}
private onFailure() {
this.failures++;
this.lastFailure = Date.now();
if (this.failures >= this.threshold) {
this.state = 'OPEN';
}
}
}
For detailed patterns: See design-patterns.md
| Anti-Pattern | Problem | Solution |
|---|---|---|
| God Object | One class does everything | Split by responsibility |
| Distributed Monolith | Microservices with tight coupling | Define proper boundaries |
| N+1 Queries | One query per item in list | Eager loading, batching |
| Premature Optimization | Optimizing before measuring | Measure, then optimize |
| Magic Numbers/Strings | Hardcoded values everywhere | Use constants/config |
| Leaky Abstraction | Implementation details exposed | Proper encapsulation |
| Circular Dependencies | A depends on B, B depends on A | Introduce abstraction |
For comprehensive anti-patterns: See anti-patterns.md
Document significant decisions for future reference:
# ADR-001: Use PostgreSQL for Primary Database
## Status
Accepted
## Context
We need to select a primary database for our application. Key requirements:
- Complex queries across related data
- Strong consistency guarantees
- Support for JSON data when needed
- Team familiarity
## Decision
We will use PostgreSQL as our primary database.
## Alternatives Considered
### MongoDB
- Pros: Flexible schema, good for rapid iteration
- Cons: Eventual consistency, complex joins difficult
### MySQL
- Pros: Widely used, good performance
- Cons: Less feature-rich than PostgreSQL
## Consequences
### Positive
- Strong ACID guarantees
- Rich query capabilities
- JSON support when needed
- Excellent tooling ecosystem
### Negative
- Stricter schema requirements
- Requires upfront data modeling
- Horizontal scaling more complex
## Notes
Review this decision if we encounter significant scaling challenges
or if data model becomes highly document-oriented.
Split when you have:
Keep together when:
Before finalizing architecture:
For comprehensive architectural guidance:
C4 Diagram Templates: references/c4-diagram-templates.md
Design Patterns: references/design-patterns.md
Anti-Patterns: references/anti-patterns.md