architecture-paradigm-service-based git:20260921.ad5ceb4A

Immutable. This exact content never changes and is served at /api/v1/blob/06cb5ddc1d295f62.

---
name: architecture-paradigm-service-based
description: Applies coarse-grained service architecture for deployment independence. Use when independent deployment is needed but shared databases rule out microservices.
alwaysApply: false
category: architectural-pattern
tags:
- architecture
- service-based
- soa
- modular
- shared-database
dependencies: []
tools: []
usage_patterns:
- paradigm-implementation
- monolith-refactoring
- deployment-independence
complexity: medium
model_hint: standard
estimated_tokens: 700
---
# The Service-Based Architecture Paradigm


## When To Use

- Multi-team organizations with domain-aligned services
- Systems requiring independent deployment of components

## When NOT To Use

- Single-team projects small enough for a monolith
- Latency-sensitive systems where inter-service calls are prohibitive

## When to Employ This Paradigm
- When teams require a degree of deployment independence but are not yet prepared for the complexity of managing numerous microservices.
- When shared databases or large-scale systems (like ERPs) make full service autonomy unrealistic.
- When establishing clear service contracts for partner teams or external consumers.

## Adoption Steps
1. **Group Capabilities**: Bundle related business functions into a small set of well-defined services, each with a designated owner.
2. **Define Service Contracts**: Publish formal specifications using standards like OpenAPI or AsyncAPI, including Service Level Agreements (SLAs) and a clear versioning strategy.
3. **Control Database Schemas**: Even when services share a database, assign explicit ownership for each schema or table. Gate all breaking changes through a formal review process.
4. **Establish Service Mediation**: Use a service registry or an API gateway to handle routing, authentication, and observability.
5. **Plan for Evolution**: Identify architectural "hotspots" that are likely candidates for being split into more granular services in the future.

## Key Deliverables
- An Architecture Decision Record (ADR) that outlines service boundaries, data ownership rules, and coordination mechanisms.
- A suite of contract tests and consumer-driven contract tests for each service to validate stability.
- Runbooks that describe deployment procedures, rollback plans, and service dependencies.

## Risks & Mitigations
- **Coupling Through a Shared Database**:
  - **Mitigation**: Changes to a shared database can have cascading effects across services. Mitigate this by using database views, replication, or a formal schema deprecation schedule to manage change.
- **Architectural Degradation**:
  - **Mitigation**: Without strong governance, this architecture can degrade into a "distributed monolith": a monolith with the added complexity of network hops. Track coupling metrics closely and enforce strict ownership of services and data to prevent this.

## Concrete Components

Vocabulary for the tools and abstractions an implementation of this
paradigm tends to carry. Not dependencies, and not ``tools:`` frontmatter.

- ``api-gateway``: single ingress that routes to coarse-grained services and centralizes cross-cutting concerns
- ``service-registry``: directory of available services with health status and contracts
- ``schema-management``: shared schema repo for types crossing service boundaries

## Exit Criteria

- [ ] An ADR outlines service boundaries, explicit data ownership per schema or table, and the
  coordination mechanism (service registry or API gateway) before any service is deployed
  independently.
- [ ] Formal service contracts (OpenAPI or AsyncAPI) with versioning and SLA statements exist
  for every inter-service interaction point.
- [ ] Consumer-driven contract tests exist for each service and pass in CI before a service
  owner merges breaking interface changes.
- [ ] Shared-database coupling hotspots are documented with a schema deprecation schedule;
  any service reading another service's tables without a view or replication layer is flagged
  as an architectural violation.