Work Order Management System — C4 Architecture Model

---

C1 — System Context

Narrative

At the system context level, the WO Management System is a subsystem within CODITECT that mediates all change control operations for regulated environments. Four actor categories interact with it: Regulated Operations Staff (system owners, QA, IT operations) who create, approve, and execute work orders through the platform interface; Vendors who receive and execute external work orders for instrument installations and qualifications; CODITECT AI Agents who autonomously create and execute work orders as part of orchestrated workflows; and Regulatory Auditors who query the immutable audit trail during inspections. The WO system connects to three external system categories: the CODITECT Core Platform (orchestrator, compliance engine, event bus), enterprise systems (CMMS, ticketing, asset management), and compliance infrastructure (certificate authority for e-signatures, policy engine).

Diagram

Compliance Implications

Every connection between the WO system and external systems is audited. Agent-initiated WOs carry the same compliance rigor as human-initiated WOs — the audit trail records the agent ID, the task that triggered the WO, and the model tier used. Regulatory auditors have read-only access to audit trails with tenant-scoped filtering; they cannot modify any records.

---

C2 — Container Diagram

Narrative

Zooming into the WO Management System boundary, it decomposes into six containers. The WO API Service is the primary entry point — a TypeScript/Express service handling REST API requests, validating inputs, and delegating to domain services. The WO Domain Services container holds the core business logic: lifecycle engine, hierarchy manager, resource matcher, approval workflow, schedule tracker, and PM automation. The WO State Store is a PostgreSQL schema (within CODITECT's existing PostgreSQL instance) holding all WO tables with RLS policies. The WO Event Emitter publishes lifecycle events to the CODITECT Event Bus using the transactional outbox pattern. The WO Adapter Layer contains integration adapters for the Agent Orchestrator, Compliance Engine, and IDE Shell. The WO Audit Archive manages long-term audit trail storage, implementing retention policies and archival to cold storage.

Diagram

Container Responsibilities

Container	Technology	Primary Responsibility	Compliance Role
WO API Service	TypeScript / Express	Request handling, validation	Input validation, rate limiting
Lifecycle Engine	TypeScript	State machine, transition rules	Audit trail generation per transition
Hierarchy Manager	TypeScript	Master/Linked WO coordination	Dependency integrity for change control
Resource Matcher	TypeScript	Capability-based assignment	Auditable assignment decisions
Approval Workflow	TypeScript	E-signature collection	FDA 21 CFR Part 11 §11.50, §11.70
Schedule Tracker	TypeScript	Duration tracking, cost attribution	Billing evidence, capacity planning
PM Automation	TypeScript	Scheduled WO generation	Preventive maintenance compliance
WO State Store	PostgreSQL	Durable state, audit trail	Immutable records, RLS isolation
Event Emitter	TypeScript	Event publishing	Real-time compliance monitoring
Adapter Layer	TypeScript / Python	Platform integration	Cross-system audit correlation
Audit Archive	PostgreSQL + GCS	Long-term retention	FDA retention requirements (7+ years)

---

C3 — Component Diagram (WO Lifecycle Engine)

Narrative

The Lifecycle Engine is the most critical component — every WO operation passes through it. It decomposes into five internal components. The State Machine defines valid transitions and enforces the transition graph (draft → pending_approval → assigned → in_progress → blocked → completed → closed). The Transition Validator applies business rules before each transition: dependency satisfaction for in_progress, approval collection for completed, compliance policy checks via the Compliance Engine. The Audit Trail Writer generates immutable audit entries for every state change — it operates within the same database transaction as the state change to guarantee consistency. The Version Controller implements optimistic locking — every UPDATE increments the version column and the application checks that the version hasn't changed since read. The Event Producer prepares typed events for the Event Emitter, using the transactional outbox pattern to ensure events are published exactly once after commit.

Diagram

Component Interfaces

Component	Input	Output	Failure Mode
State Machine	{currentStatus, requestedStatus}	Valid/Invalid + allowed transitions	Returns allowed transitions on invalid request
Transition Validator	{woId, newStatus, context}	Pass/Fail + failure reasons[]	Aggregates all failures (doesn't short-circuit)
Audit Trail Writer	{woId, action, field, old, new, actor, reason}	AuditEntry	Transaction rollback (audit and state change are atomic)
Version Controller	{woId, expectedVersion, updates}	Updated record / Conflict error	Retry with fresh version (up to 3 attempts)
Event Producer	{woId, eventType, payload}	Outbox record	Outbox write is in same transaction; polling handles delivery

---

C4 — Code Diagram (WO State Machine + Transition Validator)

Narrative

At the code level, the State Machine is implemented as a WOStateMachine class with an immutable transition map. The transition map is a Record<WOStatus, WOStatus[]> — for each status, it lists the valid target statuses. The Transition Validator is a composition of TransitionRule implementations, each responsible for one validation concern (dependency check, approval check, compliance check). Rules are evaluated in sequence and all failures are collected (fail-open pattern for diagnostics, fail-closed for execution). The AuditTrailWriter is a pure function that takes a transition context and returns an AuditEntry — the caller is responsible for persisting it within the transaction boundary.

Diagram

Design Rationale

The rule composition pattern (Strategy + Composite) ensures that new validation rules can be added without modifying existing code — critical for regulated environments where each code change requires change control. Rules are stateless and pure, making them testable in isolation. The fail-closed-with-diagnostics approach means that if any rule fails, the transition is blocked, but all failures are collected so the operator knows exactly what needs to be resolved — not just the first failure encountered.

Compliance Implications

• Every TransitionRule implementation is a testable unit with documented behavior — providing validation evidence for IQ/OQ.
• The AuditTrailWriter produces entries that satisfy FDA 21 CFR Part 11 §11.10(e) requirements: who, what, when, why.
• The VersionController prevents concurrent modification — satisfying data integrity requirements under §11.10(b).
• Rule evaluation order and results are logged, enabling reconstruction of every decision during regulatory inspection.