Activity Type Service
Component Detail
Description
Business logic layer responsible for all CRUD operations on activity types. Enforces organisational scoping (org_id), validates metadata flag combinations, and coordinates between the repository and the cache invalidation layer after mutations.
activity-type-service
Summaries
The Activity Type Service is the authoritative system of record for every activity category that peer mentors can report against. By strictly enforcing organisational boundaries, it guarantees that one organisation's activity catalogue never bleeds into another's — a critical requirement for data privacy, contractual compliance, and the integrity of cross-organisation reporting. The metadata flag validation logic protects the business from corrupted configuration states that would cause incorrect activity tracking downstream, reducing operational support costs and the risk of inaccurate impact reports reaching funders or governing bodies. As the single point of control for activity type lifecycle — including soft-deletion and reordering — it gives programme administrators full authority over their catalogue without requiring engineering intervention, improving operational agility and reducing time-to-change for client organisations.
The Activity Type Service has medium complexity and is a foundational backend dependency for multiple downstream features. It must be delivered and stabilised before the Activity Type Selection Screen, any admin management UI, and any reporting pipeline that consumes activity type metadata. The dual execution context — backend and mobile — means the service interface must be clearly versioned and any breaking changes coordinated across both deployment targets simultaneously, adding release risk if mobile and backend release cycles are misaligned. Testing requirements include unit tests for validateMetadataFlags covering all invalid flag combinations, integration tests for org-scoped isolation, and cache invalidation tests confirming the activity-type-cache-provider reflects mutations correctly.
Plan for a dedicated QA cycle around the reorderActivityTypes endpoint, as ordering bugs are subtle and high-impact for the mentor user experience.
Activity Type Service is a medium-complexity service layer running in both backend and mobile execution contexts, responsible for all CRUD and lifecycle operations on ActivityType domain objects. It owns the org-scoping contract: every read and write operation must include orgId to prevent cross-tenant data leakage — enforce this at the service boundary, not just in the repository. The validateMetadataFlags(flags) method is the core invariant guard; document all valid and invalid flag combinations explicitly and consider encoding them as a lookup table or rule set for maintainability. After any mutation (create, update, deactivate, reorder), the service must call the activity-type-cache-provider's invalidation interface to keep the mobile cache consistent — failure to do so will cause stale data bugs in the selection screen.
The repository dependency (activity-type-repository) handles raw SQL; this service maps rows to typed ActivityType domain objects, so keep the mapping logic here and avoid leaking raw row types into callers. The deactivateActivityType soft-delete pattern means filtering for active-only records must be consistently applied in all read paths.
Responsibilities
- Create, read, update, and soft-delete activity types scoped to an organisation
- Validate that metadata flag combinations are internally consistent
- Invalidate the local cache after any mutation
- Map raw database rows to typed ActivityType domain objects
Interfaces
getActivityTypesForOrg(orgId)
getActivityTypeById(id)
createActivityType(orgId, payload)
updateActivityType(id, payload)
deactivateActivityType(id)
reorderActivityTypes(orgId, orderedIds)
validateMetadataFlags(flags)
Relationships
Dependencies (2)
Components this component depends on
Dependents (2)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component