Decision Log: Arda API Proxy

Purpose

Tracks design and planning decisions for the @arda-cards/api-proxy package — covering path conventions, HTTP method authority, execution model, type derivation strategy, and scope boundaries.

Decision Table

#	Question	Status	Decision	Round
DQ-001	Path authority: spec vs. endpoint catalog	Decided	Endpoint catalog is authoritative	R1
DQ-002	HTTP method authority: spec vs. endpoint catalog	Decided	Specification is authoritative	R1
DQ-003	Execution model: single-agent vs. multi-agent	Decided	Single-agent sequential	R1
DQ-004	Type derivation strategy	Decided	Live OpenAPI primary, Kotlin fallback	R1
DQ-005	pdf-render module scope	Decided	Explicitly out of scope	R1

Round 1: Planning Decisions

DQ-001: Path Authority — Specification vs. Endpoint Catalog

Context: The specification and the documentation site’s API endpoint catalog disagree on several URL paths. Discrepancies include business affiliate roles (/business-role vs /roles), item CSV upload (/csv-upload vs /upload-job/upload-url), kanban detail queries, and order line paths. The correct paths are essential for proxy correctness.

Option	Description	Trade-offs
A	Specification paths are authoritative	Matches the preliminary spec but may diverge from actual API behavior
B	Endpoint catalog paths are authoritative	Matches the live API documentation; spec paths must be corrected

Recommendation: Option B — the endpoint catalog reflects the actual deployed API.

Decision: Option B. The actual API endpoint catalog is authoritative. The double-entity path pattern (/v1/{module}/{entity}/...) is intentional — for data authority modules, the endpoint and module names coincide. Specification paths must be corrected to match the catalog before implementation.

Applied to:

Specification — all endpoint path tables need correction
Requirements — REQ-REF-002, REQ-REF-004, REQ-RES-002, REQ-PROC-002, REQ-PROC-003, REQ-PROC-004 path tables

DQ-002: HTTP Method Authority — Specification vs. Endpoint Catalog

Context: The specification and endpoint catalog disagree on HTTP methods for several operations: kanban summary endpoints (GET vs POST), order lifecycle operations (POST vs PUT), and order add-items/add-kanban-cards (POST vs PUT).

Option	Description	Trade-offs
A	Specification methods are authoritative	Consistent with the preliminary design intent
B	Endpoint catalog methods are authoritative	May reflect the actual deployed API but could be catalog errors

Recommendation: Option A — the specification was written with deliberate method choices.

Decision: Option A. The specification is authoritative for HTTP methods. The endpoint catalog may contain errors in method attribution.

Applied to:

Specification — no changes needed (spec methods retained)
Requirements — no changes needed

DQ-003: Execution Model

Context: The project is a greenfield single-repo package with ~35 source files following a highly repetitive proxy pattern. Options range from a single-agent sequential build to multi-agent parallel implementation.

Option	Description	Trade-offs
A	Single-agent sequential (phases 1→4)	Simpler coordination, no merge conflicts, one context window; slower wall-clock time
B	Multi-agent parallel (shared infra first, then domain proxies in parallel)	Faster wall-clock time; coordination overhead, potential merge conflicts, context-window splitting

Recommendation: Option A — the repetitive structure means the sequential approach is efficient and lower-risk.

Decision: Option A. Single-agent sequential execution following the specification’s phased approach.

Applied to:

DQ-004: Type Derivation Strategy

Context: Only tenant has TypeScript types in api-mcp. The remaining 7 modules need types derived from some source. OpenAPI specs are cached in api-mcp/specs/ and available live from the staging server. Kotlin source in operations/accounts-component provides authoritative type definitions.

Option	Description	Trade-offs
A	Use cached OpenAPI specs from `api-mcp/specs/`	Available locally; may be stale
B	Fetch live OpenAPI specs from staging server	Always current; requires network access
C	Derive from Kotlin source	Most authoritative; slower, requires reading Kotlin
D	Combination: OpenAPI primary, Kotlin fallback	Best of both; two-step process

Recommendation: Option B with C as fallback — live specs are current, Kotlin resolves ambiguities.

Decision: Option B with C as fallback. Fetch live OpenAPI specs from the staging server as the primary type source. Fall back to Kotlin source in operations or accounts-component to resolve ambiguities or deficiencies in the OpenAPI spec. The api-mcp codebase is consultative only — not a primary source.

Applied to:

Specification § Per-Module Types
Run project plans — type derivation tasks reference this strategy

DQ-005: pdf-render Module Scope

Context: The goal lists pdf-render (/v1/pdf-render, Print category) in the API endpoints table. The specification does not include a PdfRenderProxy or any Print domain directory.

Option	Description	Trade-offs
A	Include pdf-render in scope	Adds a proxy; increases scope by ~3 files
B	Explicitly exclude pdf-render	Reduces scope; can be added in a future project

Recommendation: Option B — keep the initial release focused on the core domains.

Decision: Option B. pdf-render is explicitly out of scope for this project. Marked as such in the goal’s API Endpoints table.

Applied to:

Goal — Status column set to Out of scope for pdf-render