d42c653eea
- engineering-docs → archive/2026-03-29-engineering-docs (63/63 tasks complete) - phase-2-production-ready → archive/2026-03-29-phase-2-production-ready (89/89 tasks complete) - openspec/specs/ synced with all Phase 1 + Phase 2 + engineering-docs capabilities (22 specs total) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.6 KiB
3.6 KiB
ADDED Requirements
Requirement: Service deep-dive documents
The system SHALL include a document (docs/engineering/05-services.md) providing a deep-dive reference for every core service and component, following a consistent template: Purpose → Responsibility boundary → Public interface → Key methods → Database schema (if applicable) → Error types → Configuration.
Scenario: AgentService documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the AgentService section covering: responsibility (agent CRUD only), public methods (createAgent, getAgent, listAgents, updateAgent, deleteAgent), the
agentstable schema, AgentNotFoundError and AgentAlreadyExistsError, and what AgentService does NOT do (no auth, no credentials — Single Responsibility)
Scenario: OAuth2Service documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the OAuth2Service section covering: responsibility (token issuance and revocation only), public methods (issueToken, validateToken, revokeToken), Redis token storage schema, JWT payload structure, token TTL configuration, and the Vault credential verification path vs bcrypt path
Scenario: CredentialService documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the CredentialService section covering: responsibility (credential lifecycle only), public methods (generateCredential, rotateCredential, revokeCredential, listCredentials), the
credentialstable schema, bcrypt vs Vault storage decision, and thevault_pathcolumn purpose
Scenario: AuditService documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the AuditService section covering: responsibility (immutable audit logging only), public methods (logEvent, queryLogs), the
audit_logstable schema, event types enum, 90-day retention policy, and why audit records are never updated or deleted
Scenario: VaultClient documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the VaultClient section covering: purpose (wraps node-vault for KV v2 operations), public methods (writeSecret, readSecret, verifySecret, deleteSecret), the opt-in configuration (VAULT_ADDR env var), and the constant-time comparison in verifySecret and why it matters (timing attack prevention)
Scenario: OPA policy engine documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the OPA section covering: purpose (dynamic access control beyond static OAuth scopes), how policies are loaded, how authorization decisions are made, the policy file locations, and how to write and test a new policy
Scenario: Web Dashboard documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the Web Dashboard section covering: React 18 + Vite 5 + TypeScript structure, how it authenticates against the AgentIdP API, the main views (agent list, credential management, audit log viewer, policy editor), and how to run it locally
Scenario: Monitoring stack documented
- WHEN a new engineer reads 05-services.md
- THEN they SHALL find the monitoring section covering: Prometheus metrics exposed by the API server (
/metrics), the key metrics (request count, latency histograms, active tokens, agent count), Grafana dashboard structure, and how to add a new metric to the API server
Scenario: Consistent template enforced
- WHEN a new engineer looks up any service
- THEN every service section SHALL follow the same template so the engineer knows exactly where to find each type of information