template/examples/DECISIONS.example.md

Atlas Desk Decisions

ADR-001: Start With A Modular Monolith

Status

Accepted

Date

2026-06-28

Context

Atlas Desk is new, the team is small, and the request workflow domain is still evolving. The system needs clear boundaries, but it does not yet need independent service deployments.

Problem

The team must choose an architecture that supports maintainability without adding unnecessary operational complexity.

Alternatives

Alternative	Summary
Layered monolith	Simple, but feature ownership can blur over time.
Modular monolith	Clear module boundaries with one deployable unit.
Microservices	Strong service isolation but adds network, deployment, and data consistency cost.

Pros

• Keeps deployment simple.
• Supports explicit module ownership.
• Allows future service extraction if boundaries prove stable.

Cons

• Requires discipline to maintain module boundaries.
• Scaling is initially at the application level, not module level.

Decision

Use a modular monolith for the first production release.

Consequences

• Module dependency rules are documented in the architecture guide.
• Cross-module writes are not allowed without an application-level command.
• Microservice extraction will be reconsidered only after measured pressure.

ADR-002: Use PostgreSQL As The Primary Data Store

Status

Accepted

Date

2026-06-28

Context

Atlas Desk needs transactional consistency for request state, assignment, notes, and audit events.

Problem

The team needs a reliable primary database that supports relational queries, transactions, and reporting-friendly indexes.

Alternatives

Alternative	Summary
PostgreSQL	Strong relational database with good operational support.
Document database	Flexible schema but weaker fit for transactional queue workflows.
Embedded database	Simple locally but not suitable for shared production usage.

Pros

• Strong transactions.
• Mature indexing and query capabilities.
• Good fit for reporting queries.
• Broad hosting support.

Cons

• Schema changes require migration discipline.
• Query performance must be monitored as data grows.

Decision

Use PostgreSQL as the primary data store.

Consequences

• Migrations must be reviewed before release.
• Integration tests should run against PostgreSQL, not an incompatible in-memory substitute.
• Backup and restore procedures are production readiness requirements.

ADR-003: Require Backend Authorization For All Sensitive Actions

Status

Accepted

Date

2026-06-28

Context

The frontend hides actions based on role, but API clients cannot be trusted to enforce authorization.

Problem

Sensitive actions such as assignment, closure, and audit viewing must be protected even if a user bypasses the UI.

Alternatives

Alternative	Summary
Frontend-only checks	Better user experience but not a security boundary.
Backend policy checks	Trusted enforcement point.
Database row-level security	Strong but more complex than needed initially.

Pros

• Keeps authorization in a trusted boundary.
• Makes behavior testable through API integration tests.
• Supports multiple clients later.

Cons

• Requires explicit policy coverage for each sensitive endpoint.
• UI and API authorization rules can drift without tests.

Decision

Enforce authorization in backend policies for all sensitive actions.

Consequences

• Frontend checks remain usability hints only.
• Authorization tests are required for each protected workflow.
• Policy changes must be reviewed as security-sensitive changes.

ADR-004: Use Repository Pattern For Persistence Boundaries

Status

Accepted

Date

2026-06-28

Context

Atlas Desk uses PostgreSQL and Entity Framework Core, but request workflow rules should not depend directly on ORM APIs or database-specific query details.

Problem

Direct persistence access from application services would make workflow logic harder to test and increase coupling to storage implementation details.

Alternatives

Alternative	Summary
Direct database context access	Simple, but spreads persistence concerns through application logic.
Generic repository	Hides the ORM, but exposes low-value CRUD abstractions.
Domain-specific repositories	Keeps persistence behind workflow-focused interfaces.

Pros

• Keeps workflow services focused on use cases.
• Makes request assignment and audit behavior easier to test.
• Provides intention-revealing query methods.
• Allows persistence implementation changes without rewriting domain logic.

Cons

• Adds interface and implementation classes.
• Requires discipline to avoid generic CRUD repositories.
• Complex queries still need explicit performance review.

Decision

Use domain-specific repositories for persistence boundaries.

Consequences

• RequestRepository owns request persistence operations.
• UserRepository owns user lookup persistence operations.
• Reporting uses explicit read queries instead of mutating request data.
• Transaction boundaries remain visible in application services.