docs: initialize engineering starter kit

examples/DECISIONS.example.md

@@ -0,0 +1,150 @@
+# 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.