diff --git a/docs/specs/store-api.spec.md b/docs/specs/store-api.spec.md new file mode 100644 index 0000000..eb6dc48 --- /dev/null +++ b/docs/specs/store-api.spec.md @@ -0,0 +1,433 @@ +# Store API Specification + +## Overview + +The Store API is a core service for the Backend-Driven UI (BDUI) system that manages UI configuration storage, real-time updates, and analytics for dynamic user interfaces across multiple platforms (Android, iOS, Web). It provides a centralized key-value storage system with notification capabilities and change tracking for UI configurations. + +## Architecture + +### Core Components + +1. **Configuration Store**: Key-value storage for UI screen configurations +2. **Real-time Notification System**: WebSocket-based updates for configuration changes +3. **Version Management**: Diffs and versioning for configuration changes +4. **Analytics Engine**: User interaction and screen usage tracking +5. **Multi-platform Support**: Consistent behavior across platforms + +### Key Features + +- **Dynamic UI Updates**: Real-time configuration changes without app store updates +- **Version Control**: Track and manage configuration versions with diffs +- **Analytics**: Monitor user interactions and screen performance +- **Multi-platform**: Support for Android, iOS, and Web platforms +- **Admin Panel Integration**: Visual editing and management interface + +## Data Structure + +### Configuration Store + +```typescript +interface ConfigurationStore { + id: ID + key: ConfigurationKey + value: ConfigurationValue + version: SemanticVersion + platform: Platform + metadata: ConfigurationMetadata + createdAt: Date + updatedAt: Date + publishedAt?: Date + status: ConfigurationStatus +} +``` + +### Configuration Key + +```typescript +interface ConfigurationKey { + screenId: string + platform: Platform + variant?: string // For A/B testing + locale?: string // For i18n + userId?: string // For user-specific configs +} +``` + +### Configuration Value + +```typescript +interface ConfigurationValue { + schema: Schema + components: Component[] + layout: LayoutConfiguration + styles: StyleConfiguration + interactions: InteractionConfiguration + analytics: AnalyticsConfiguration +} +``` + +### Platform Enumeration + +```typescript +enum Platform { + ANDROID = 'android', + IOS = 'ios', + WEB = 'web', + UNIVERSAL = 'universal' +} +``` + +### Configuration Status + +```typescript +enum ConfigurationStatus { + DRAFT = 'draft', + PUBLISHED = 'published', + DEPRECATED = 'deprecated', + ARCHIVED = 'archived' +} +``` + +## Methods + +### Factory Methods + +- `static create(key: ConfigurationKey, value: ConfigurationValue, platform: Platform)` - Creates new configuration +- **Returns:** New ConfigurationStore instance +- **Throws:** ValidationError, DuplicateKeyError +- **Emits:** ConfigurationCreatedEvent + +### Storage Methods + +- `store(key: ConfigurationKey, value: ConfigurationValue)` - Stores configuration +- **Throws:** ValidationError, StorageError +- **Emits:** ConfigurationStoredEvent + +- `retrieve(key: ConfigurationKey)` - Retrieves configuration +- **Returns:** ConfigurationValue | null +- **Throws:** NotFoundError + +- `update(key: ConfigurationKey, value: ConfigurationValue)` - Updates configuration +- **Throws:** ValidationError, NotFoundError +- **Emits:** ConfigurationUpdatedEvent + +- `delete(key: ConfigurationKey)` - Deletes configuration +- **Throws:** NotFoundError +- **Emits:** ConfigurationDeletedEvent + +### Version Management + +- `createVersion(key: ConfigurationKey, changes: ConfigurationChange[])` - Creates new version +- **Returns:** New ConfigurationStore instance +- **Throws:** ValidationError, VersionConflictError +- **Emits:** ConfigurationVersionCreatedEvent + +- `getVersionHistory(key: ConfigurationKey)` - Gets version history +- **Returns:** ConfigurationVersion[] +- **Throws:** NotFoundError + +- `getDiff(key: ConfigurationKey, fromVersion: SemanticVersion, toVersion: SemanticVersion)` - Gets configuration diff +- **Returns:** ConfigurationDiff +- **Throws:** NotFoundError, VersionNotFoundError + +### Real-time Updates + +- `subscribe(key: ConfigurationKey, callback: ConfigurationUpdateCallback)` - Subscribes to updates +- **Returns:** SubscriptionId +- **Throws:** SubscriptionError + +- `unsubscribe(subscriptionId: SubscriptionId)` - Unsubscribes from updates +- **Throws:** SubscriptionError + +- `notifyUpdate(key: ConfigurationKey, change: ConfigurationChange)` - Notifies subscribers +- **Emits:** ConfigurationUpdateNotificationEvent + +### Analytics + +- `trackInteraction(key: ConfigurationKey, interaction: UserInteraction)` - Tracks user interaction +- **Throws:** ValidationError +- **Emits:** UserInteractionTrackedEvent + +- `getAnalytics(key: ConfigurationKey, timeRange: TimeRange)` - Gets analytics data +- **Returns:** AnalyticsData +- **Throws:** NotFoundError + +- `getUsageStats(key: ConfigurationKey)` - Gets usage statistics +- **Returns:** UsageStatistics +- **Throws:** NotFoundError + +### Platform Management + +- `getPlatformConfigs(platform: Platform)` - Gets all configurations for platform +- **Returns:** ConfigurationStore[] +- **Throws:** PlatformError + +- `syncAcrossPlatforms(key: ConfigurationKey)` - Syncs configuration across platforms +- **Throws:** SyncError +- **Emits:** ConfigurationSyncedEvent + +## Business Rules + +1. **Unique Keys**: Configuration keys must be unique within the same platform +2. **Version Increment**: New versions must have higher semantic version numbers +3. **Platform Compatibility**: Configurations must be valid for their target platform +4. **Real-time Updates**: All configuration changes must be broadcast to subscribers +5. **Analytics Tracking**: All user interactions must be tracked for analytics +6. **Access Control**: Only authorized users can modify configurations +7. **Validation**: All configurations must pass schema validation before storage +8. **Rollback Capability**: Previous versions must be accessible for rollback +9. **Performance**: Configuration retrieval must be optimized for real-time usage +10. **Data Integrity**: Configuration changes must maintain data consistency + +## Dependencies + +### Base Classes + +- Entity + +### Value Objects + +- ID +- ConfigurationKey +- ConfigurationValue +- SemanticVersion +- Platform +- ConfigurationStatus +- ConfigurationMetadata + +### Domain Events + +- ConfigurationCreatedEvent +- ConfigurationStoredEvent +- ConfigurationUpdatedEvent +- ConfigurationDeletedEvent +- ConfigurationVersionCreatedEvent +- ConfigurationUpdateNotificationEvent +- UserInteractionTrackedEvent +- ConfigurationSyncedEvent + +### Domain Errors + +- ValidationError +- DuplicateKeyError +- StorageError +- NotFoundError +- VersionConflictError +- VersionNotFoundError +- SubscriptionError +- PlatformError +- SyncError + +### External Services + +- WebSocketService (for real-time notifications) +- AnalyticsService (for user interaction tracking) +- CacheService (for performance optimization) +- DatabaseService (for persistent storage) + +## Implementation Details + +### Storage Strategy + +The Store API uses a hybrid storage approach: + +1. **Primary Storage**: PostgreSQL for persistent configuration storage +2. **Cache Layer**: Redis for high-performance configuration retrieval +3. **Real-time Layer**: WebSocket connections for live updates +4. **Analytics Storage**: Time-series database for interaction tracking + +### Key-Value Structure + +``` +Key Format: {platform}:{screenId}:{variant}:{locale}:{userId} +Value Format: JSON configuration with schema validation +``` + +### Notification System + +- **WebSocket Connections**: Maintained per client for real-time updates +- **Event Broadcasting**: Configuration changes broadcast to all subscribers +- **Filtering**: Clients receive only relevant configuration updates +- **Retry Logic**: Failed notifications are retried with exponential backoff + +### Version Management + +- **Semantic Versioning**: Major.Minor.Patch versioning scheme +- **Change Tracking**: Detailed diff tracking for all configuration changes +- **Rollback Support**: Ability to revert to previous versions +- **Migration Support**: Automatic migration for breaking changes + +### Analytics Integration + +- **Interaction Tracking**: User clicks, scrolls, and navigation events +- **Performance Metrics**: Screen load times and rendering performance +- **Usage Statistics**: Screen popularity and user engagement +- **A/B Testing**: Support for configuration variants and testing + +## Tests + +### Essential Tests + +- Configuration storage and retrieval with valid/invalid keys +- Version management and diff generation +- Real-time notification delivery +- Analytics data collection and retrieval +- Platform-specific configuration handling +- Error handling for all failure scenarios +- Performance testing for high-load scenarios +- Integration testing with external services + +### Performance Tests + +- Configuration retrieval latency (< 100ms) +- Real-time notification delivery (< 50ms) +- Concurrent user support (10,000+ users) +- Storage capacity (1M+ configurations) +- Analytics data processing (100K+ events/minute) + +### Security Tests + +- Access control validation +- Data encryption verification +- SQL injection prevention +- XSS protection for stored configurations +- Rate limiting for API endpoints + +## API Endpoints + +### Configuration Management + +``` +GET /api/v1/configurations/{key} # Retrieve configuration +POST /api/v1/configurations # Store configuration +PUT /api/v1/configurations/{key} # Update configuration +DELETE /api/v1/configurations/{key} # Delete configuration +``` + +### Version Management + +``` +GET /api/v1/configurations/{key}/versions # Get version history +POST /api/v1/configurations/{key}/versions # Create new version +GET /api/v1/configurations/{key}/diff # Get configuration diff +``` + +### Real-time Updates + +``` +WS /api/v1/configurations/ws # WebSocket connection +POST /api/v1/configurations/{key}/subscribe # Subscribe to updates +DELETE /api/v1/configurations/{key}/subscribe # Unsubscribe from updates +``` + +### Analytics + +``` +POST /api/v1/analytics/interactions # Track user interaction +GET /api/v1/analytics/{key} # Get analytics data +GET /api/v1/analytics/{key}/stats # Get usage statistics +``` + +### Platform Management + +``` +GET /api/v1/platforms/{platform}/configs # Get platform configurations +POST /api/v1/configurations/{key}/sync # Sync across platforms +``` + +## Error Handling + +### Error Types + +- **ValidationError**: Invalid configuration data or key format +- **DuplicateKeyError**: Configuration key already exists +- **StorageError**: Database or cache operation failure +- **NotFoundError**: Configuration not found +- **VersionConflictError**: Version conflict during update +- **SubscriptionError**: WebSocket subscription failure +- **PlatformError**: Platform-specific operation failure +- **SyncError**: Cross-platform synchronization failure + +### Error Response Format + +```typescript +interface ErrorResponse { + error: { + code: string + message: string + details?: Record + timestamp: Date + requestId: string + } +} +``` + +## Monitoring and Observability + +### Metrics + +- Configuration retrieval latency +- Real-time notification delivery rate +- Storage operation success rate +- Analytics data processing rate +- WebSocket connection count +- Error rates by operation type + +### Logging + +- All configuration operations +- Real-time notification events +- Analytics data collection +- Error conditions and stack traces +- Performance metrics +- Security events + +### Alerts + +- High error rates (> 5%) +- Slow response times (> 500ms) +- Storage capacity warnings (> 80%) +- WebSocket connection failures +- Analytics data processing delays + +## Security Considerations + +### Access Control + +- Role-based access control (RBAC) +- API key authentication +- JWT token validation +- Rate limiting per user/IP +- Input validation and sanitization + +### Data Protection + +- Encryption at rest and in transit +- Secure key generation +- Data anonymization for analytics +- GDPR compliance for user data +- Audit logging for all operations + +## Scalability + +### Horizontal Scaling + +- Stateless service design +- Load balancer distribution +- Database sharding by platform +- Cache cluster distribution +- WebSocket connection distribution + +### Performance Optimization + +- Configuration caching +- Database query optimization +- CDN for static configurations +- Compression for large configurations +- Batch processing for analytics + +## Metadata + +Version: 1.0.0 +Last Updated: 2025-01-27 +Location: `packages/domain/src/store-api/entities/configuration-store.entity.ts` \ No newline at end of file diff --git a/docs/task/task-description.md b/docs/task/task-description.md new file mode 100644 index 0000000..e21b52d --- /dev/null +++ b/docs/task/task-description.md @@ -0,0 +1,185 @@ +**Service with Backend-Driven Approach to Building User Interfaces** +_Technical Specification_ + +--- + +## 1. Context and Relevance + +Avito is a Russian online service for posting ads about goods, real estate, jobs, resumes, and services, ranking first in the world among classifieds sites. +Each week, dozens of new features and experiments are added to the product, which must be simultaneously supported across multiple platforms: Android, iOS, and Web. + +Mobile releases require store moderation, slowing delivery and increasing the cycle from idea to launch. This complicates rapid iteration and A/B testing. + +**Release Process:** + +1. **Monitoring & Regression Testing** — crash data collection, functional verification, fixing critical bugs. +2. **Gradual Rollout** — after successful testing, the release is rolled out to a percentage of users on iOS and Android. If problems are found, the cycle repeats. +3. **Fixes & Restrictions** — only critical fixes are allowed during testing/rollout. No new features. +4. **Final Release** — if no issues, updates are released to all users. + +**Backend-Driven UI (BDUI)** shifts interface-building logic partially or fully to the server, enabling fast screen structure/content changes without rebuilding apps. +For Avito, this means: + +- Faster delivery of changes +- Reduced developer workload +- Increased flexibility & scalability + +--- + +## 2. Task Description + +You must develop a **backend-driven UI framework** for Avito — a platform that manages user interfaces for Android, iOS, and Web apps via centralized configuration. + +**Requirements:** + +- Service for storing UI screen JSON configurations +- Admin panel for editing configurations for interfaces. +- Support at all platforms (Android/iOS/Web) where apps fetch configs from server and render screens. +- Real-time editing of screens **without app updates**. +- Analytics: which screens/elements users interact with and how long. +- **Demo:** implement provided screen layouts using your approach. + +**Optional (bonus):** + +- A/B testing support +- Template reuse/inheritance +- Multi-platform support +- Internationalization (i18n) +- Conditional rendering logic +- Interactive UI components (clicks, navigation, forms) +- Ability to describe logic + +--- + +## 3. Software & Hardware Requirements + +**Hardware:** + +- Android smartphone/emulator (API 24+) or iOS (14+) +- Modern web browser (Chrome/Firefox/Safari) + +**Software (recommended stack):** + +- Backend: TypeScript +- Config storage: JSON + PostgreSQL +- Frontend/Web: React +- Mobile: Android (Kotlin), iOS (Swift) +- Admin panel: Web UI (shadcn/ui) +- Analytics: Firebase, Amplitude + +--- + +## 4. Presentation/Demo Requirements + +- Short architecture & principle description +- Admin panel demo: screen assembly + instant update on client app +- Client demo (Android/iOS/Web) fetching configs correctly +- Analytics demo (usage stats for screens/elements) + +--- + +## 5. Documentation Requirements + +- **README:** project launch instructions (backend, admin, client) +- Short architecture description (diagrams, sequence flows) +- Example config files (JSON/YAML) +- Documentation for additional functionality (analytics, A/B, i18n, etc.) +- Scalability documentation for other platforms + +--- + +## 6. Resources + +- [Scenario Layout (Figma)](https://www.figma.com/design/fPrvzQcUQdX0ddXunxDhHS/%D0%9B%D0%A6%D0%A2.-%D0%90%D0%B2%D0%B8%D1%82%D0%BE?node-id=0-1&t=V11m3gwCMUZx3ODc-1) +- [Figma Guidelines](https://www.figma.com/design/DglrdmxGmbi3VwIWfchxhi/--23--%D0%93%D0%B0%D0%B9%D0%B4%D0%BB%D0%B0%D0%B9%D0%BD%D1%8B-%D0%B4%D0%BB%D1%8F-%D0%B4%D0%B8%D0%B7%D0%B0%D0%B9%D0%BD%D0%B5%D1%80%D0%B0?node-id=501-11022&p=f&t=mUY5PxGlL1fvf7pv-0) +- Avito Design Materials (on site) +- [Avito Mobile Meetup (YouTube)](https://www.youtube.com/live/kP6Ev8k5ixg) + +--- + +## 7. Deliverables + +**Intermediate Submission:** + +- Service for storing screen layouts +- Basic admin panel +- App for rendering JSON configs + +**Final Submission:** + +- Implement provided layout using your solution + +**Bonus Features:** + +- A/B testing +- Template reuse/inheritance +- i18n +- Conditional rendering logic +- Interactive UI components + +--- + +## 8. Evaluation Criteria + +### Team Approach + +- **Assessed:** Organization, transparency, communication, decomposition, risk/data handling +- **Artifacts:** + + - Problem statement, goals, success metrics, assumptions, boundaries + - Decomposition & prioritization: board/plan, critical path, DoR/DoD + - Risk registry with mitigations + - Data-driven decisions/experiments + - Documentation: ADRs, diagrams, README, CI checklists + +### Technical Solution + +- **Assessed:** BDUI architecture, code quality, testing, performance, reliability, security, scalability, DX +- **Artifacts:** + + - Architecture: layers, component contracts, schema/DSL versioning, backward compatibility + - Code quality: modularity, readability, linting, typing + - Tests: unit/contract/e2e for backend/admin/client + - Performance: latency/CPU/RAM budgets, cold start, caching + - Reliability: error handling, config rollback, feature flags + - Security: config validation, logic restrictions, admin permissions + - Observability: logs, metrics, tracing, alerts + - CI/CD: builds, contract checks, preview envs + - Cross-platform support & design system compliance + +### Task Fit + +- **Assessed:** How well the solution meets case requirements & demo scenario + +- **Must have:** + + - Config storage service (JSON/React DSL) + - Admin panel for visual UI assembly + - Client on at least one platform + - Real-time editing without app store updates + - Usage analytics + - Demo of given layout + +- **Optional:** A/B tests, template reuse, multi-platform, i18n, conditional logic, interactivity, logic description + +### Effectiveness + +- **Assessed:** Practical usefulness: iteration speed, ownership cost, stability, product impact +- **Metrics:** + + - Performance: config fetch/render latency, size, caching + - Economy & DX: onboarding simplicity, screen assembly speed, docs quality + - Flexibility: feature flags, partial rollout, version compatibility + - Bonus: meaningful SLOs, pre/post metrics (how BDUI reduces release cycle) + +### Pitch Session (Final) + +- **Assessed:** Story clarity, live demo, Q\&A, roadmap +- **Artifacts:** + + - Structure: problem → solution → architecture → demo → metrics → risks → plans + - Demo: admin screen build + instant client render; analytics demo + - Clarity/timing: within slot, no overload + - Q\&A: confident answers, tradeoffs knowledge + - Materials: slides, demo script, backup plan + - Bonus: live metrics, honest risk review