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>
41 lines
3.6 KiB
Markdown
41 lines
3.6 KiB
Markdown
## 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 `agents` table 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 `credentials` table schema, bcrypt vs Vault storage decision, and the `vault_path` column 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_logs` table 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
|