synaptic-labs-ai/pact-plugin/pact-architecture-patterns

                    +------------------+
                    |   External User  |
                    +--------+---------+
                             |
                             v
+------------------+    +----+----+    +------------------+
| Payment Gateway  |<-->|   Your  |<-->|   Email Service  |
+------------------+    | System  |    +------------------+
                        +---------+
                             ^
                             |
                    +--------+---------+
                    |   Admin User     |
                    +------------------+

+----------------------------------------------------------------+
|                         Your System                             |
|  +----------------+     +----------------+     +--------------+ |
|  |   Web App      |     |    API         |     |   Database   | |
|  |   (React)      |---->|    (Node.js)   |---->|   (Postgres) | |
|  +----------------+     +----------------+     +--------------+ |
|                               |                                 |
|                               v                                 |
|                         +----------+                            |
|                         |  Cache   |                            |
|                         | (Redis)  |                            |
|                         +----------+                            |
+----------------------------------------------------------------+

+---------------------------------------------------------------+
|                         API Container                          |
|  +-------------+    +-------------+    +-------------------+  |
|  | Controllers |    |  Services   |    |   Repositories    |  |
|  |             |--->|             |--->|                   |  |
|  | UserCtrl    |    | UserService |    | UserRepository    |  |
|  | OrderCtrl   |    | OrderService|    | OrderRepository   |  |
|  +-------------+    +-------------+    +-------------------+  |
|                           |                                    |
|                           v                                    |
|                    +-------------+                             |
|                    |   Clients   |                             |
|                    | PaymentAPI  |                             |
|                    | EmailClient |                             |
|                    +-------------+                             |
+---------------------------------------------------------------+

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

// 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": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ],
    "request_id": "req_abc123"
  }
}

// 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 } });
  }
  // ...
}

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;
  }
}

Mobile App  -->  Mobile BFF  -->
                                   Core Services
Web App     -->  Web BFF     -->

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';
    }
  }
}

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