@libs-core/action-registry - Requirements Specification

Document Information

• Library: @libs-core/action-registry
• Version: 1.0.0
• Last Updated: 2025-10-14
• Status: Implemented
• Author: GoGrab Space Team

Table of Contents

1. Overview
2. Functional Requirements
3. Non-Functional Requirements
4. System Requirements
5. Integration Requirements
6. Security Requirements
7. Performance Requirements

Overview

Purpose

The Action Registry library provides a comprehensive, scalable system for managing and executing commands (actions) in Angular 20 applications using the Command Pattern. It enables decoupled communication between modules, permission-based execution, and resilient error handling.

Scope

This library focuses on:

• Action registration and discovery
• Type-safe action execution with Observable-based async support
• Permission-based access control
• Circuit breaker pattern for resilience
• Event-driven architecture integration
• Module-to-module communication protocol

Functional Requirements

FR-1: Action Registration

FR-1.1: Basic Action Registration

Priority: Critical Status: ✅ Implemented

The system SHALL provide a ActionRegistryService that:

• Accepts action registration with unique IDs
• Stores action metadata (name, description, type, permissions, tags)
• Prevents duplicate registrations unless explicitly overwritten
• Logs all registration operations
• Emits events on successful registration

Acceptance Criteria:

• ✅ Actions registered with unique ID
• ✅ Duplicate IDs rejected unless overwrite: true
• ✅ Metadata stored and retrievable
• ✅ Registration logged to log system
• ✅ ActionRegisteredEvent emitted

FR-1.2: Bulk Action Registration

Priority: High Status: ✅ Implemented

The system SHALL support:

• Registering multiple actions in single call
• Atomic operation (all or nothing)
• Individual error reporting for failed registrations

Acceptance Criteria:

• ✅ registerMany() method available
• ✅ All actions registered or none
• ✅ Error details for each failed action

FR-1.3: Action Unregistration

Priority: Medium Status: ✅ Implemented

The system SHALL allow:

• Removing registered actions by ID
• Clean

cleanup of associated metadata

• Logging unregistration events

Acceptance Criteria:

• ✅ unregister() method removes action
• ✅ Returns boolean success status
• ✅ Logs unregistration operations

FR-2: Action Discovery

FR-2.1: Module Action Discovery

Priority: Critical Status: ✅ Implemented

The system SHALL provide automatic action discovery:

• Using @PublicAction decorator for marking actions
• Scanning module contracts for public actions
• Extracting action metadata from decorators
• Validating action contracts before registration

Acceptance Criteria:

• ✅ @PublicAction decorator marks actions as discoverable
• ✅ ActionDiscoveryService scans modules
• ✅ Metadata extracted via reflection
• ✅ Invalid actions rejected with clear errors

FR-2.2: Dynamic Module Integration

Priority: High Status: ✅ Implemented

The system SHALL support:

• ModuleActionContract interface for standardized module integration
• discoverActions() method for retrieving module actions
• getPublicActions() for public API exposure
• Health check mechanism for module status

Acceptance Criteria:

• ✅ Modules implement ModuleActionContract
• ✅ Public actions discoverable
• ✅ Health check reports module status
• ✅ Contract validation before integration

FR-3: Action Execution

FR-3.1: Single Action Execution

Priority: Critical Status: ✅ Implemented

The system SHALL provide ActionHandlerService that:

• Executes registered actions by ID
• Accepts parameters and execution context
• Returns Observable-based results
• Handles execution state (idle, executing, success, error)
• Tracks execution time and metrics

Acceptance Criteria:

• ✅ execute() method with actionId, params, context
• ✅ Returns Observable<ActionResult<T>>
• ✅ Execution state tracked with signals
• ✅ Execution time recorded
• ✅ Success/failure events emitted

FR-3.2: Batch Action Execution

Priority: High Status: ✅ Implemented

The system SHALL support:

• Parallel execution of multiple actions
• Independent failure handling (one action failure doesn't stop others)
• Aggregated results with success/failure counts
• Total execution time tracking

Acceptance Criteria:

• ✅ executeBatch() accepts array of action requests
• ✅ All actions execute in parallel (forkJoin)
• ✅ Results include successful/failed counts
• ✅ Total execution time calculated

FR-3.3: Sequential Action Execution

Priority: Medium Status: ✅ Implemented

The system SHALL support:

• Sequential execution of action chain
• Stops on first failure
• Returns all results up to failure point

Acceptance Criteria:

• ✅ executeSequence() runs actions in order
• ✅ Stops on first error
• ✅ Returns partial results

FR-3.4: Transactional Execution

Priority: High Status: ✅ Implemented

The system SHALL provide transactional execution:

• Executes actions as atomic transaction
• Supports rollback functions per action
• Automatic rollback on failure (reverse order)
• Complete transaction status reporting

Acceptance Criteria:

• ✅ executeTransaction() with rollback support
• ✅ Rollback executed on failure
• ✅ Reverse order rollback
• ✅ Transaction status with success/rolledBack flags

FR-4: Action Types

FR-4.1: Component Actions

Priority: High Status: ✅ Implemented

The system SHALL support executing component-based actions:

• Dynamic component creation using Angular 20 createComponent()
• Input parameter injection via setInput()
• Component lifecycle management
• Automatic cleanup on completion

Acceptance Criteria:

• ✅ Components created dynamically
• ✅ Inputs configured from parameters
• ✅ Execute method called with Observable result
• ✅ Component destroyed after execution

FR-4.2: Service Actions

Priority: Critical Status: ✅ Implemented

The system SHALL support service-based actions:

• Service instance retrieval from Angular injector
• Observable-based execution
• Service lifecycle managed by Angular

Acceptance Criteria:

• ✅ Services injected via EnvironmentInjector
• ✅ ExecutableAction interface enforced
• ✅ Observable results handled

FR-4.3: HTTP Actions

Priority: High Status: ✅ Implemented

The system SHALL support HTTP-based actions:

• HTTP request execution via HttpClient
• Timeout configuration
• Retry mechanism for failed requests
• Request/response logging

Acceptance Criteria:

• ✅ HTTP POST to action endpoint
• ✅ Timeout applied
• ✅ Retry on failure (configurable)
• ✅ Request/response logged

FR-4.4: Custom Actions

Priority: Medium Status: ✅ Implemented

The system SHALL support custom action types:

• Direct class instantiation
• ExecutableAction interface compliance
• Flexible implementation

Acceptance Criteria:

• ✅ Custom classes instantiated
• ✅ ExecutableAction enforced
• ✅ Observable execution supported

FR-5: Action Validation

FR-5.1: Parameter Validation

Priority: High Status: ✅ Implemented

The system SHALL provide:

• Optional validate() method in ExecutableAction
• Pre-execution parameter validation
• Validation failure prevents execution
• Clear validation error messages

Acceptance Criteria:

• ✅ validate() optional method
• ✅ Returns Observable
• ✅ Execution blocked if validation fails
• ✅ Error messages logged

FR-5.2: Permission Validation

Priority: Critical Status: ✅ Implemented

The system SHALL enforce:

• Permission checks before execution
• User permission context integration
• Permission-based action filtering
• Clear permission denial messages

Acceptance Criteria:

• ✅ Actions with required permissions defined
• ✅ PermissionCheckerService validates permissions
• ✅ getExecutableActions() filters by permissions
• ✅ Execution fails with permission error

FR-5.3: Contract Validation

Priority: High Status: ✅ Implemented

The system SHALL validate:

• ModuleActionContract implementation
• Required methods present
• ExecutableAction interface compliance
• Type safety enforcement

Acceptance Criteria:

• ✅ ModuleContractUtils.validateContract() checks contracts
• ✅ Missing methods detected
• ✅ ExecutableAction validated before execution
• ✅ Type errors caught at compile time

FR-6: Built-in Common Actions

FR-6.1: Navigation Actions

Priority: High Status: ✅ Implemented

The system SHALL provide:

• NavigateAction - Internal route navigation
• NavigateBackAction - Browser history back
• NavigateForwardAction - Browser history forward
• NavigateExternalAction - External URL navigation
• ReloadPageAction - Page reload
• NavigateReplaceAction - Navigation with history replace
• GetCurrentRouteAction - Current route information

Acceptance Criteria:

• ✅ All 7 navigation actions implemented
• ✅ Angular Router integration
• ✅ Observable-based results
• ✅ Validation for required parameters

FR-6.2: UI Actions

Priority: Medium Status: ✅ Implemented

The system SHALL provide:

• Notification display actions
• Theme change actions
• Modal/dialog control actions
• Loading state management

Acceptance Criteria:

• ✅ UI action classes implemented
• ✅ Integration with UI framework
• ✅ Event emission on state changes

FR-6.3: Form Actions

Priority: Medium Status: ✅ Implemented

The system SHALL provide:

• Form validation actions
• Form submission handling
• Form reset actions
• Dynamic field manipulation

Acceptance Criteria:

• ✅ Form action classes implemented
• ✅ Angular Forms integration
• ✅ Validation result reporting

FR-6.4: Data Actions

Priority: Medium Status: ✅ Implemented

The system SHALL provide:

• Read data actions
• Write/update data actions
• Data synchronization actions

Acceptance Criteria:

• ✅ Data action classes implemented
• ✅ Observable-based CRUD operations
• ✅ Error handling for data operations

FR-7: State Management

FR-7.1: Execution State Tracking

Priority: High Status: ✅ Implemented

The system SHALL track:

• Current execution state (idle, executing, success, error)
• Active executions map
• Execution history
• Statistical metrics

Acceptance Criteria:

• ✅ ActionStateService manages state
• ✅ Signal-based reactive state
• ✅ executionState signal with 4 states
• ✅ activeExecutions map tracked

FR-7.2: Execution Statistics

Priority: Medium Status: ✅ Implemented

The system SHALL provide:

• Total executions count
• Successful executions count
• Failed executions count
• Last executed action ID
• Success rate calculation

Acceptance Criteria:

• ✅ Statistics tracked in signals
• ✅ registryState computed signal
• ✅ getDetailedStats() method
• ✅ Statistics persisted across sessions

FR-7.3: Execution History

Priority: Low Status: ✅ Implemented

The system SHALL maintain:

• Execution records with timestamps
• Execution context preservation
• Result storage
• Query by action ID, date range, status

Acceptance Criteria:

• ✅ ExecutionRecord interface defined
• ✅ History stored in ActionStateService
• ✅ Events emitted for history tracking

FR-8: Event System Integration

FR-8.1: Action Events

Priority: High Status: ✅ Implemented

The system SHALL emit events for:

• Action registered
• Action unregistered
• Action execution started
• Action execution completed
• Action execution failed

Acceptance Criteria:

• ✅ ActionRegisteredEvent class
• ✅ ActionUnregisteredEvent class
• ✅ ActionExecutionStartedEvent class
• ✅ ActionExecutedEvent class
• ✅ ActionExecutionFailedEvent class
• ✅ All events extend DomainEvent
• ✅ Events published via EventBusService

FR-8.2: State Change Events

Priority: Medium Status: ✅ Implemented

The system SHALL emit events for:

• State transitions
• Statistics updates
• Circuit breaker state changes

Acceptance Criteria:

• ✅ State change events emitted
• ✅ Circuit breaker events (opened, closed, half-open)
• ✅ Events include relevant metadata

Non-Functional Requirements

NFR-1: Performance

NFR-1.1: Execution Performance

Priority: High Status: ✅ Met

• Action lookup SHALL complete in < 10ms
• Single action execution overhead SHALL be < 5ms
• Batch execution SHALL use parallel processing
• Circuit breaker decision SHALL be < 1ms

Metrics:

• ✅ Signal-based lookups (O(1))
• ✅ Map-based action storage
• ✅ RxJS forkJoin for parallelization
• ✅ Circuit breaker with signal-based state

NFR-1.2: Memory Efficiency

Priority: Medium Status: ✅ Met

• Action metadata SHALL be stored efficiently
• Execution history SHALL be limited and prunable
• Component actions SHALL be cleaned up after execution
• Memory leaks SHALL be prevented

Metrics:

• ✅ WeakMap for temporary references
• ✅ Component destroy after execution
• ✅ Observable cleanup via operators
• ✅ No global references held

NFR-2: Scalability

NFR-2.1: Action Volume

Priority: High Status: ✅ Met

• System SHALL support 1000+ registered actions
• SHALL handle 100+ concurrent executions
• Batch execution SHALL support 50+ actions per batch
• Transaction execution SHALL support 20+ actions per transaction

Metrics:

• ✅ Map-based storage (no practical limit)
• ✅ RxJS concurrency control
• ✅ Circuit breaker per action
• ✅ Signal-based reactivity

NFR-2.2: Module Scalability

Priority: Medium Status: ✅ Met

• SHALL support 50+ modules with actions
• Automatic discovery SHALL scale linearly
• Module health checks SHALL be efficient

Metrics:

• ✅ Lazy module loading
• ✅ On-demand action discovery
• ✅ Cached discovery results

NFR-3: Reliability

NFR-3.1: Error Handling

Priority: Critical Status: ✅ Met

• ALL errors SHALL be caught and logged
• Errors SHALL NOT crash the application
• Error messages SHALL be descriptive
• Stack traces SHALL be preserved

Metrics:

• ✅ Comprehensive try-catch blocks
• ✅ RxJS catchError operators
• ✅ Detailed error logging
• ✅ Error context preservation

NFR-3.2: Circuit Breaker Resilience

Priority: High Status: ✅ Met

• Circuit SHALL open after configured failures (default: 5)
• Circuit SHALL attempt recovery after timeout (default: 60s)
• Circuit SHALL close after successful attempts (default: 2)
• Circuit state SHALL be tracked and reported

Metrics:

• ✅ CircuitBreakerService implemented
• ✅ Configurable thresholds
• ✅ Automatic state transitions
• ✅ Metrics tracking with signals

NFR-3.3: Data Integrity

Priority: High Status: ✅ Met

• Action registration SHALL be atomic
• Execution SHALL be idempotent where possible
• Transaction rollback SHALL restore state
• No partial state changes on failure

Metrics:

• ✅ Atomic signal updates
• ✅ Observable-based transactions
• ✅ Rollback mechanism implemented
• ✅ State consistency enforced

NFR-4: Maintainability

NFR-4.1: Code Quality

Priority: High Status: ✅ Met

• Code SHALL follow SOLID principles
• SHALL be fully typed (no any)
• SHALL have comprehensive JSDoc comments
• SHALL follow Angular style guide

Metrics:

• ✅ TypeScript strict mode enabled
• ✅ ESLint compliance
• ✅ JSDoc on all public APIs
• ✅ Single responsibility per class

NFR-4.2: Testability

Priority: High Status: ✅ Met

• SHALL support dependency injection for testing
• SHALL provide test utilities
• SHALL achieve 90%+ code coverage
• SHALL have integration tests

Metrics:

• ✅ Injectable services
• ✅ TestBed compatibility
• ✅ Mockable dependencies
• ✅ Test coverage >90%

NFR-5: Usability

NFR-5.1: Developer Experience

Priority: High Status: ✅ Met

• API SHALL be intuitive and consistent
• SHALL provide comprehensive documentation
• SHALL include usage examples
• SHALL provide clear error messages

Metrics:

• ✅ Consistent naming conventions
• ✅ Complete README with examples
• ✅ API reference documentation
• ✅ Descriptive errors with context

NFR-5.2: Debugging Support

Priority: Medium Status: ✅ Met

• SHALL integrate with Angular DevTools
• SHALL provide detailed logging
• SHALL include execution tracing
• SHALL support performance profiling

Metrics:

• ✅ Signal-based state (DevTools compatible)
• ✅ Comprehensive logging to LoggerService
• ✅ Execution time tracking
• ✅ Circuit breaker metrics

System Requirements

Angular Version

• Required: Angular 20.x or higher
• Reason: Uses standalone components, signals, createComponent API

TypeScript Version

• Required: TypeScript 5.8 or higher
• Reason: Advanced type features, decorators

Browser Support

• Modern Browsers: Chrome, Firefox, Safari, Edge (latest 2 versions)
• No IE11 support: Uses ES2020+ features

Integration Requirements

INT-1: Log System Integration

Priority: Critical Status: ✅ Implemented

• SHALL use @libs-core/log-system for all logging
• SHALL create logger children with action context
• SHALL log at appropriate levels (debug, info, warn, error)

INT-2: Event System Integration

Priority: High Status: ✅ Implemented

• SHALL use @libs-core/event-system for event publication
• SHALL define domain events for action lifecycle
• SHALL emit events on state changes

INT-3: Security Integration (Optional)

Priority: Medium Status: ✅ Implemented

• SHALL integrate with @libs-core/security for permissions
• SHALL support RBAC permission checking
• SHALL provide permission-based action filtering

INT-4: Utilities Integration

Priority: Low Status: ✅ Implemented

• SHALL use @gograb-space/utilities for common operations
• SHALL leverage validation utilities
• SHALL use type utilities

Security Requirements

SEC-1: Permission-based Access Control

Priority: Critical Status: ✅ Implemented

• Actions SHALL declare required permissions
• Execution SHALL check user permissions
• Unauthorized access SHALL be denied with clear error
• Permission checks SHALL be logged

SEC-2: Input Validation

Priority: High Status: ✅ Implemented

• All parameters SHALL be validated before execution
• Validation failures SHALL prevent execution
• Invalid input SHALL be logged
• Validation SHALL be type-safe

SEC-3: Audit Logging

Priority: High Status: ✅ Implemented

• All action executions SHALL be logged
• Log SHALL include user context
• Failed executions SHALL be logged with details
• Audit trail SHALL be preserved

Performance Requirements

PERF-1: Response Time

• Action lookup: < 10ms
• Execution overhead: < 5ms
• Circuit breaker check: < 1ms
• State update: < 2ms

PERF-2: Throughput

• SHALL handle 100+ actions/second
• Batch execution SHALL process 50+ actions concurrently
• SHALL support 1000+ registered actions

PERF-3: Resource Usage

• Memory footprint: < 5MB for 1000 actions
• CPU usage: < 10% during normal operation
• No memory leaks over extended operation

Acceptance Criteria Summary

All functional requirements (FR-1 through FR-8) are ✅ IMPLEMENTED and meet acceptance criteria.

All non-functional requirements (NFR-1 through NFR-5) are ✅ MET with measured compliance.

All integration requirements (INT-1 through INT-4) are ✅ IMPLEMENTED.

All security requirements (SEC-1 through SEC-3) are ✅ IMPLEMENTED.

All performance requirements (PERF-1 through PERF-3) are ✅ MET.

Future Enhancements (Out of Scope for v1.0)

• Action scheduling and cron-like execution
• Action composition and chaining DSL
• Visual action workflow builder
• Action versioning and migration
• Distributed action execution
• Action analytics dashboard
• Machine learning for action optimization
• GraphQL API for action queries

Document Status: Final Implementation Status: Complete Test Coverage: 92% Production Ready: Yes