feat: establish architecture decision record process and enhance existing openEHR and FastAPI ADRs.

Author: platzhersh

docs/adr/0000-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# 0. Record architecture decisions
+
+Date: 2026-01-04
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/adr/0001-use-openehr.md

@@ -1,42 +1,27 @@
-# ADR 0001: Use openEHR for Clinical Data
+# 1. Use openEHR for Clinical Data
+
+Date: 2026-01-02
 
 ## Status
 
 Accepted
 
 ## Context
 
-We need a data model and storage solution for clinical data (observations, diagnoses, medications, encounters). Options considered:
+We need a data model and storage solution for clinical data including observations, diagnoses, medications, and encounters. Three approaches were considered: designing a custom relational schema with our own tables for each clinical concept, adopting HL7 FHIR resources with a FHIR server, or using openEHR archetypes with EHRBase as the clinical data repository.
 
-1. **Custom relational schema** - Design our own tables for each clinical concept
-2. **HL7 FHIR** - Use FHIR resources and a FHIR server
-3. **openEHR** - Use openEHR archetypes and EHRBase
+A custom relational schema would give us complete control over the data model and allow rapid initial development, but we would need to design and maintain schemas for every clinical concept ourselves. HL7 FHIR offers a mature, widely-adopted standard with extensive tooling and community support, but FHIR servers can be complex to deploy and the resource-based model may not align perfectly with our learning goals. openEHR provides archetype-based modeling where clinical concepts are defined in reusable, version-controlled archetypes maintained by the international openEHR community, separating the clinical data model from the software implementation.
 
 ## Decision
 
-We will use **openEHR** with **EHRBase** as the clinical data repository.
-
-## Rationale
+We will use openEHR with EHRBase as the clinical data repository.
 
-- **Archetype-based modeling**: Clinical concepts are defined in reusable, version-controlled archetypes maintained by the openEHR community
-- **Separation of concerns**: Data model (archetypes) is separate from software implementation
-- **Query language**: AQL (Archetype Query Language) provides powerful querying across clinical structures
-- **EHRBase maturity**: Open-source, actively maintained, good REST API
-- **Learning opportunity**: Explore openEHR ecosystem for clinical data management
+EHRBase is an open-source, actively maintained openEHR server that provides a well-documented REST API. Clinical data will be stored as compositions following openEHR templates, while application-specific data like user accounts and audit logs will remain in a separate PostgreSQL database. We will link patient medical record numbers to openEHR EHR IDs through a PatientRegistry table in our application database.
 
 ## Consequences
 
-### Positive
-- Rich clinical modeling with community-maintained archetypes
-- Standardized data that could interoperate with other openEHR systems
-- AQL for complex clinical queries
+This decision means we gain access to rich clinical modeling capabilities with community-maintained archetypes, producing standardized data that could potentially interoperate with other openEHR systems. The Archetype Query Language (AQL) will enable us to perform complex queries across clinical structures in ways that would be difficult with traditional SQL.
 
-### Negative
-- Learning curve for openEHR concepts (compositions, archetypes, templates)
-- Need to manage two databases (EHRBase + app DB)
-- Template creation/management adds complexity
+However, we accept a steeper learning curve as the team must understand openEHR concepts including compositions, archetypes, and templates. We will need to manage two separate databases: EHRBase for clinical data and PostgreSQL for application data. Template creation and management adds operational complexity compared to a simple relational schema.
 
-### Mitigations
-- Start with simple templates
-- Keep app-specific data (users, audit) in separate PostgreSQL database
-- Use PatientRegistry to link MRN to EHR ID
+To mitigate these challenges, we will start with simple templates focusing on basic vital signs before expanding to more complex clinical scenarios. Keeping application-specific concerns in the PostgreSQL database allows us to use familiar tools and patterns where openEHR semantics are unnecessary.

docs/adr/0002-fastapi-backend.md

@@ -1,49 +1,29 @@
-# ADR 0002: Use FastAPI for Backend
+# 2. Use FastAPI for Backend
+
+Date: 2026-01-02
 
 ## Status
 
 Accepted
 
 ## Context
 
-We need a backend framework to:
-- Serve REST API endpoints
-- Integrate with EHRBase (HTTP client)
-- Integrate with PostgreSQL (Prisma)
-- Handle async operations efficiently
+We need a backend framework to serve REST API endpoints, integrate with EHRBase via HTTP, integrate with PostgreSQL through Prisma, and handle async operations efficiently.
 
-Options considered:
-1. **FastAPI** (Python) - Modern async Python framework
-2. **Express/Fastify** (Node.js) - JavaScript/TypeScript backend
-3. **Django** (Python) - Full-featured Python framework
-4. **Go** - High-performance compiled language
+Four approaches were considered. FastAPI is a modern Python framework with first-class async/await support and automatic OpenAPI documentation. Express or Fastify on Node.js would provide JavaScript/TypeScript consistency with the frontend and excellent async patterns. Django offers a full-featured Python framework with an extensive ecosystem and built-in admin interface. Go would provide high performance and strong typing through a compiled language.
 
-## Decision
+The backend will primarily perform I/O-bound operations: making HTTP requests to EHRBase, executing database queries, and serving JSON responses. These operations benefit more from efficient async handling than raw CPU performance. The team values type safety for catching errors early, automatic API documentation for development velocity, and a gentle learning curve that allows focus on openEHR concepts rather than framework complexity.
 
-We will use **FastAPI** with **Python 3.11+**.
+## Decision
 
-## Rationale
+We will use FastAPI with Python 3.11 or later as the backend framework.
 
-- **Async-first**: Native async/await support, important for I/O-bound operations (HTTP to EHRBase, database queries)
-- **Type hints**: First-class Pydantic integration for request/response validation
-- **OpenAPI**: Automatic API documentation generation
-- **Learning curve**: Python is accessible, FastAPI is well-documented
-- **Ecosystem**: Good libraries for HTTP (httpx), database (Prisma), testing (pytest)
+We will use httpx as the async HTTP client for communicating with EHRBase, prisma-client-py for database access, pydantic-settings for configuration management, and pytest-asyncio for testing. All application code will use Python's native async/await syntax, and we will leverage Pydantic models throughout the service and API layers for consistent type validation.
 
 ## Consequences
 
-### Positive
-- Clean async code with httpx for EHRBase communication
-- Automatic request validation and documentation
-- Pydantic models shared between API and service layers
-
-### Negative
-- Python type system less strict than TypeScript or Go
-- Need virtual environment management
-- Slightly more complex deployment than Node.js
-
-### Technical Decisions
-- Use `httpx` for async HTTP client (EHRBase)
-- Use `prisma-client-py` for database access
-- Use `pydantic-settings` for configuration
-- Use `pytest-asyncio` for testing
+FastAPI's async-first architecture allows us to write clean, readable code for concurrent I/O operations without blocking threads or managing callback chains. The automatic request validation and OpenAPI documentation generation means we spend less time writing boilerplate validation code and manually maintaining API specifications. Pydantic models can be shared between API endpoints and service layers, ensuring type consistency throughout the application.
+
+However, Python's type system is less strict than TypeScript or Go, relying on optional static analysis with mypy rather than compile-time guarantees. We will need to manage Python virtual environments for dependency isolation, adding a step to the development setup compared to Node.js or Go. Deployment is slightly more complex than Node.js containerized applications, as we must ensure the correct Python runtime and activate virtual environments appropriately.
+
+The learning curve for FastAPI and async Python is accessible enough that developers can become productive quickly, allowing the team to focus energy on understanding openEHR rather than fighting the framework.

…/adr/0001-openehr-template-management.md …/adr/0003-openehr-template-management.mddocs/adr/0001-openehr-template-management.md renamed to docs/adr/0003-openehr-template-management.md docs/adr/0001-openehr-template-management.md renamed to docs/adr/0003-openehr-template-management.md

@@ -1,6 +1,9 @@
-# ADR-0001: openEHR Template Management
+# 3. openEHR Template Management
+
+Date: 2026-01-03
 
 ## Status
+
 Accepted
 
 ## Context
@@ -9,16 +12,11 @@ Open CIS uses EHRBase as its openEHR Clinical Data Repository. EHRBase requires
 
 Templates define the structure of clinical data by constraining openEHR archetypes. For example, a "Vital Signs" template combines observation archetypes for blood pressure and pulse within an encounter composition archetype.
 
-### Problem
-
-1. Templates must be uploaded to EHRBase before the application can store clinical data
-2. Developers may forget to upload templates when setting up a new environment
-3. Different environments (dev, staging, prod) need consistent template configurations
-4. Creating proper OPT files from scratch requires specialized tooling and expertise
+Templates must be uploaded to EHRBase before the application can store clinical data, but developers may forget this step when setting up a new environment. Different environments like development, staging, and production need consistent template configurations to ensure the same clinical data structures work everywhere. Creating proper OPT files from scratch requires specialized tooling and expertise that would slow down development and introduce a barrier to entry for new contributors.
 
 ## Decision
 
-We will implement automatic template registration on API startup, using pre-built templates from the openEHR community:
+We will implement automatic template registration on API startup, using pre-built templates from the openEHR community.
 
 1. **Template Storage**: OPT files are stored in `api/templates/` directory, named `{template_id}.opt`
 

…0003-direct-httpx-openehr-integration.md …0004-direct-httpx-openehr-integration.mddocs/adr/0003-direct-httpx-openehr-integration.md renamed to docs/adr/0004-direct-httpx-openehr-integration.md docs/adr/0003-direct-httpx-openehr-integration.md renamed to docs/adr/0004-direct-httpx-openehr-integration.md

@@ -1,11 +1,14 @@
-# ADR-0003: Direct httpx Integration for openEHR API
+# 4. Direct httpx Integration for openEHR API
+
+Date: 2026-01-04
 
 ## Status
+
 Accepted
 
 ## Context
 
-Open CIS needs to interact with EHRBase (an openEHR Clinical Data Repository) to create, retrieve, and query clinical compositions. We must decide how to implement this integration: use an existing SDK/library or build a custom client using a low-level HTTP library.
+Open CIS needs to interact with EHRBase, an openEHR Clinical Data Repository, to create, retrieve, and query clinical compositions. We must decide how to implement this integration: use an existing SDK or library, or build a custom client using a low-level HTTP library.
 
 ### Problem