ADR 0005 — /api/v1/afia, EndpointUri, ai-agent/ layout

Status: accepted
Date: 2026-09-19

Context

Afia already has EndpointUri and a Flutter ApiConfig that can drift if paths are copied by hand.

Decision

• Canonical HTTP paths: health.afia.app.common.EndpointUri only. docs/api-map.md is an index.
• Mobile prefix stays /api/v1/afia; host via --dart-define=AFIA_API_BASE_URL.
• Envelope later: { data, status, message, errors } — add when the first write endpoint exists.
• Agent tree at workspace root ai-agent/: adr/, docs/, memory/, tasks/.

Reserved prefixes (not implemented):

Prefix	Context
/api/v1/afia/health	liveness (exists)
/api/v1/afia/app-version	force-update (exists)
/api/v1/afia/auth	identity
/api/v1/afia/me	current account
/api/v1/afia/appointments	patient booking
/api/v1/afia/clinician	clinician
/api/v1/afia/orders	diagnostics
/api/v1/afia/worklists	diagnostics
/api/v1/afia/admin	admin

Consequences

• New endpoints require an EndpointUri constant before a controller.
• Flutter must not invent paths; copy from EndpointUri / api-map.