Component ↔ Story Traceability Mapping¶
Purpose: Provide bidirectional visibility between architecture components (API internals) and implemented user stories to support impact analysis, test coverage review, and change management.
Legend¶
- Component Category: Controller | Service | Adapter | Library | External
- Story IDs: As per
docs/stories/*.md. - Gap: Anticipated future stories needed to fully exercise component.
1. Mapping Table¶
| Component | Category | Core Responsibility | Related Stories | Gap / Future Story Seeds |
|---|---|---|---|---|
Auth Controller (authCtrl) |
Controller | Signup, login, token refresh, MFA (future) | US-101, US-102, US-103 | MFA flow (future), password reset story, SSO button initiation (US-106) |
Tenant Provisioning Controller (tenantCtrl) |
Controller | Tenant creation & configuration | US-101 | Advanced tenant settings, billing plan selection |
Employee Profile Controller (empCtrl) |
Controller | Employee profile CRUD & read views | US-301, US-302 | Self-edit boundaries, org chart, bulk import |
Leave Management Controller (leaveCtrl) |
Controller | Leave balances, request submission, cancellation | US-311, US-312, US-313 | Partial-day requests, complex accrual tiers |
Billing Controller (billingCtrl) |
Controller | Plan management & subscription status exposure | US-205 | Downgrade story, invoicing view |
Identity Service (identitySvc) |
Service | Credential mgmt & federated mapping | US-101, US-102, US-103 | SSO integration (US-106), password reset service |
Tenant Service (tenantSvc) |
Service | Tenant lifecycle & isolation metadata | US-101 | Tenant settings update story, plan enforcement |
Employee Service (employeeSvc) |
Service | Profile aggregation, validation, custom fields | US-301, US-302 | Audit reporting story, search/filter employees |
Leave Engine (leaveEngine) |
Service | Accrual calculations, balance ops, cancellation reversal | US-311, US-312, US-313 | Carry-over rules, tenure-based accrual tiers |
Billing Integration (billingSvc) |
Service | Gateway webhooks and proration | US-205 | Downgrade & credit calc story, advanced reconciliation job |
Document Adapter (docAdapter) |
Adapter | Upload, scan & signed URL orchestration | US-204 | Versioning, bulk import, OCR enrichment |
Notification Adapter (notifyAdapter) |
Adapter | Email dispatch & templating | US-102, US-103, US-312 | Reminder emails, escalation notifications |
Event Publisher (eventPublisher) |
Service | Domain event serialization to broker | US-101, US-102, US-103, US-301, US-311, US-312, US-313, US-321, US-322, US-331, US-205 | Event version governance (US-401) |
Analytics Emitter (analyticsEmitter) |
Service | Analytics event emission (activation, usage, performance) | US-101, US-102, US-103, US-301, US-311, US-312, US-321, US-322, US-331, US-332 | Performance metrics emission, version governance (US-401) |
Isolation Guard (isolationGuard) |
Library | Enforce tenant predicate on queries | US-101, US-301, US-302, US-311, US-312, US-321, US-322, US-331 | Automated guardrail tests story |
Permission Service (permissionSvc) |
Service | Role-based and field-level authorization | US-301 (field-level), US-302 (custom field edit), US-311, US-312, US-321, US-322, US-331, US-332 | Advanced role matrix management story |
Event Broker (queue) |
External | Domain + analytics event transport | All emitting stories (updated incl. US-205, US-332) | DLQ monitoring, replay tooling story, schema version registry integration (US-401) |
Primary Database (db) |
External | Multi-tenant relational persistence | All CRUD stories | Sharding / partitioning performance story |
Cache (cache) |
External | Tenant-scoped ephemeral data | US-311 (accrual), US-312 (balance) | Profile caching performance tuning story |
Identity Provider (idp) |
External | Federated authentication | US-106 | Password-less reauth story |
Email Service (emailSvc) |
External | Transactional email delivery | US-102, US-103, US-312 | Bounce handling & deliverability metrics |
Payment Gateway (payments) |
External | Subscription & billing events | (None yet) | Subscription lifecycle story |
Document Service (docsvc) |
External | Antivirus scan & storage abstraction | US-204 | Bulk upload, OCR enrichment story |
Observability (obs) |
External | Telemetry sinks (logs/traces/metrics) | All stories (non-functional instrumentation), US-402 | Performance budget doc, automated coverage drift alert |
2. Story Coverage Summary¶
| Domain | Implemented Stories | Key Components Exercised | Not Yet Exercised Components |
|---|---|---|---|
| Identity & Access | US-101, US-102, US-103 | authCtrl, identitySvc, tenantCtrl, notifyAdapter, eventPublisher, analyticsEmitter, isolationGuard | SSO (idp), password reset flow |
| Employee Profile | US-301, US-302 | empCtrl, employeeSvc, permissionSvc, isolationGuard, eventPublisher, analyticsEmitter | Document adapter, profile search optimization |
| Leave Management | US-311, US-312 | leaveCtrl, leaveEngine, cache, eventPublisher, analyticsEmitter, notifyAdapter | Advanced accrual tiers, cancellation flow |
| Recruitment | US-321, US-322 | (Recruitment controllers not yet explicit) eventPublisher, analyticsEmitter, permissionSvc | Recruitment-specific controller/service, applicant notification adapter |
| Performance Goals | US-331 | permissionSvc, eventPublisher, analyticsEmitter, isolationGuard | Goal analytics summarization service |
3. Gap Analysis¶
- Billing layer entirely unmapped (billingCtrl, billingSvc) – requires subscription management stories.
- Document flow (docAdapter, docsvc) lacks initial CRUD/upload story – risks late integration & security oversight.
- IdP (SSO) integration deferred – plan to introduce early to validate federated claims mapping.
- Observability coverage: instrumentation present by reference; need explicit span coverage audit story.
- Event versioning & schema evolution not represented – create governance story to prevent breaking consumers.
4. Recommended Next Stories (Seeds)¶
| Proposed Story ID (Temp) | Title | Components Targeted | Rationale |
|---|---|---|---|
| US-106 | SSO Login & Mapping | authCtrl, identitySvc, idp | Early validation of federation & claim mapping |
| US-204 | Document Upload & Antivirus Scan | docAdapter, docsvc, eventPublisher | Enables secure document handling & tests adapter |
| US-205 | Subscription Plan Upgrade | billingCtrl, billingSvc, payments, tenantSvc | Exercises billing integration & proration logic |
| US-313 | Leave Request Cancellation | leaveCtrl, leaveEngine, eventPublisher | Completes lifecycle & negative balance logic |
| US-332 | Goal Progress Analytics Event | analyticsEmitter, permissionSvc | Adds performance insights & instrumentation depth |
| US-401 | Event Schema Version Governance | eventPublisher, analyticsEmitter, queue | Prevent consumer breakage & ensure evolution strategy |
| US-402 | Span Coverage Audit | obs, isolationGuard, core services | Improve trace-based diagnostics |
5. Traceability Maintenance Process¶
- Update table when a new story is added or a component changes responsibility.
- During refinement, ensure each planned story references at least one under-exercised component.
- Before release, verify critical components (auth, isolation, billing, documents) have test-backed stories.
- Link this doc from
docs/INDEX.mdunder Quality/Architecture cross-cutting section.
6. Open Questions¶
- Separate recruitment controller/service naming? (e.g.,
jobCtrl,applicantCtrl) - Do we need dedicated analytics aggregation services now or post-MVP?
- Will billing require a distinct reconciliation job component? (Add when story defined.)
- Should isolationGuard produce explicit audit events for blocked cross-tenant attempts?
Version: 1.0 (2025-11-22)