Software Architecture Patterns

The layered pattern organizes software into horizontal layers, each with a specific responsibility. Requests flow through each layer sequentially, and each layer only communicates with adjacent layers. This is our default pattern for new microservices unless a more specialized pattern is justified.

Layer Diagram

Example: Search Service Layered Structure

// Layered architecture example from our Search Service
// Layer 1: API Controller
class SearchController {
  constructor(private service: SearchService) {}
  async search(query: SearchQuery): Promise<SearchResults> {
    return this.service.executeSearch(query);
  }
}

// Layer 2: Application Service
class SearchService {
  constructor(
    private repo: ArticleRepository,
    private cache: SearchCache
  ) {}
  async executeSearch(query: SearchQuery): Promise<SearchResults> {
    const cached = await this.cache.get(query.id);
    if (cached) return cached;
    const results = await this.repo.search(query);
    this.cache.set(query.id, results);
    return results;
  }
}

// Layer 3: Repository (Data Access)
class ElasticsearchRepository implements ArticleRepository {
  async search(query: SearchQuery): Promise<SearchResults> {
    return this.client.search({ index: 'articles', body: query });
  }
}

The Aevum Encyclopedia platform is organized as a collection of ~45 microservices, each owning a specific domain and capable of independent deployment. Services communicate via synchronous HTTP/gRPC calls and asynchronous messaging through our event bus.

Service Communication Flow

Service Boundaries

Our services are bounded by Domain-Driven Design (DDD) strategic patterns. Each service maps to a bounded context:

• Content Service — Article creation, editing, versioning
• Search Service — Full-text search, faceting, ranking
• Translation Service — AI-powered multi-language translation
• Auth Service — User identity, OAuth, RBAC
• Notification Service — Email, push, in-app notifications
• Analytics Service — Page views, reading patterns, metrics

Event-driven architecture decouples services by having them communicate through an event broker. Services publish events when state changes occur and subscribe to events of interest. This is the backbone of our real-time content pipeline and translation workflow.

Event Flow: Article Published

Event Schema Example

{
  "specversion": "1.0",
  "id": "evt_2f8d7a3b",
  "type": "aevum.content.article.published",
  "source": "content-service",
  "time": "2025-03-15T10:30:00Z",
  "data": {
    "articleId": "art_9f3c2e1a",
    "title": "Quantum Computing",
    "language": "en",
    "version": 14,
    "authorId": "usr_7b4e1d2c",
    "categoryIds": ["cat_science", "cat_technology"],
    "wordCount": 2847
  }
}

CQRS separates the responsibility for updating data (Commands) from the responsibility for reading data (Queries). At Aevum Encyclopedia, we use CQRS primarily in the Content Service and Analytics Service, where read and write workloads differ significantly.

Code Example: Command Handler

// Command — modifies state
class PublishArticleCommand implements Command {
  readonly articleId: string;
  readonly title: string;
  readonly content: string;
  readonly authorId: string;
}

class PublishArticleHandler implements CommandHandler<PublishArticleCommand> {
  async execute(cmd: PublishArticleCommand): Promise<void> {
    // Validate, apply business rules, persist to write DB
    const article = await this.repo.findById(cmd.articleId);
    article.publish(cmd.title, cmd.content);
    await this.repo.save(article);
    await this.bus.publish(new ArticlePublishedEvent(article));
  }
}

// Query — reads optimized data
class GetArticleByIdQuery implements Query<ArticleDTO> {
  readonly articleId: string;
}

class GetArticleByIdHandler implements QueryHandler<GetArticleByIdQuery, ArticleDTO> {
  async execute(query: GetArticleByIdQuery): Promise<ArticleDTO> {
    // Read from optimized read model (Elasticsearch)
    return this.readModel.get(query.articleId);
  }
}

Hexagonal architecture isolates the core business logic from external concerns by defining ports (interfaces) and adapters (implementations). This pattern is used in all mission-critical services at Aevum Encyclopedia to ensure the domain logic remains testable and framework-independent.

Key Principles

• Domain first: Business logic depends on nothing external
• Inbound ports: Interfaces defined by the domain for how it can be used (use cases)
• Outbound ports: Interfaces defined by the domain for external capabilities it needs
• Adapters: Concrete implementations of ports (REST controllers, DB repositories, message producers)
• Dependency inversion: Frameworks adapt to the domain, not vice versa

Event sourcing stores state changes as a sequence of events rather than just the current state. This is used in the Article Versioning Service to maintain a complete audit trail of every edit, review, and approval — essential for a collaborative encyclopedia platform.

Event Stream for an Article

Serverless functions are used for bursty, event-driven tasks that don't warrant dedicated service infrastructure. At Aevum Encyclopedia, serverless handles image processing, PDF generation, sitemap updates, and CDN cache invalidation.

When to Use Serverless

We use Istio as our service mesh to handle cross-cutting concerns at the infrastructure level — service discovery, load balancing, mutual TLS, traffic splitting, and observability — without modifying application code.

Service Mesh Capabilities

• mTLS: Automatic mutual TLS encryption between all services
• Circuit Breaking: Automatic isolation of failing services
• Canary Deployments: Traffic splitting for gradual rollouts
• Rate Limiting: Global and per-service rate policies
• Observability: Distributed tracing, metrics, and access logs

1. Distributed Monolith

Services that are tightly coupled and must be deployed together, but are distributed across separate codebases. This gives you all the complexity of microservices with none of the benefits. Signal: if changing one service requires coordinated changes in three others, you have a distributed monolith.

2. Chatty Services

Services that require multiple round-trips to complete a simple operation. This adds latency, increases failure surface, and makes debugging extremely difficult. Solution: batch operations, use aggregation services, or reconsider boundaries.

3. Shared Database Anti-Pattern

Multiple services sharing the same database. This creates tight coupling at the data layer and prevents independent deployment. Rule: each service owns its own database. If data sharing is needed, use events or a materialized view service.

4. Over-Engineering

Applying complex patterns (CQRS, Event Sourcing, Saga) to problems that don't require them. YAGNI principle: start simple and add complexity only when you have measurable evidence that it's needed.

Decision Flow

1. Start with a modular monolith — apply layered architecture within bounded modules
2. Extract to microservices only when: independent scaling is needed, different teams own the domain, or technology heterogeneity is required
3. Add event-driven communication when: services need to react to state changes asynchronously, or when building real-time pipelines
4. Apply CQRS when: read and write workloads have fundamentally different performance requirements, or when you need optimized read views
5. Use Event Sourcing when: complete audit trails are required, or when you need to replay history for temporal queries
6. Consider Hexagonal for any service where testability and framework independence are priorities
7. Serverless for edge workloads — image processing, notifications, scheduled tasks, webhooks