Epic: orchestrator

[Haydart]

Epic: Wallet Management Orchestrator

Overview

Implement a cache-first wallet management orchestrator that provides fast access to wallet portfolio data for memecoin
launch operations. The system leverages existing domain models (WalletInfo, ScheduledFundingInfo, LaunchInfo)
and service facades to minimize Solana RPC costs through intelligent Firebase caching with user-controlled blockchain data refresh.

Architecture Decisions

• Cache-First Pattern: Firebase as primary data source, Solana queries only for manual refresh
• Service Integration: Leverage existing SimpleFirebaseService (WalletsDataService) and SimpleSolanaService (SolanaDataService)
• Domain Model Reuse: Leverage existing WalletInfo, ScheduledFundingInfo, LaunchInfo, TokenHolding models without modification
• Response Wrapper: Implement CachedWalletResponse model for cache freshness indicators
• Standalone Implementation: No integration with existing domain architecture or pump.fun workflows
• Manual Operations: User-triggered refresh only, no automatic data updates or real-time listeners
• MVP Simplicity: No RPC backup or failover logic - simple direct service calls

Technical Approach

Backend Services

• WalletManagementOrchestrator: Core orchestration class coordinating between existing services
• SimpleFirebaseService (existing): Implements WalletsDataService for Firebase cache operations
• SimpleSolanaService (existing): Implements SolanaDataService for blockchain queries
• Cache Response Models: CachedWalletResponse wrapper for freshness tracking

Integration Points

• Service Initialization: Orchestrator initializes and manages both SimpleFirebaseService and SimpleSolanaService instances
• Cache-First Logic: Query Firebase first via SimpleFirebaseService, refresh from Solana via SimpleSolanaService on demand
• Data Flow: Solana → SimpleSolanaService → Orchestrator → SimpleFirebaseService → Firebase cache
• Response Wrapping: Orchestrator wraps Firebase responses with cache freshness metadata
• Token Holdings: SimpleSolanaService.get_token_holdings() returns List[TokenHolding], cached via SimpleFirebaseService
• WalletInfo Fields: Existing model includes first_funded_at, last_balance_sol, launch_count, updated_at fields for orchestrator use
• Status Updates: Orchestrator handles automatic status updates (0.25 SOL threshold = FUNDED) during refresh operations

API Layer

• FastAPI Endpoints: 13 endpoints across 4 categories (core, refresh, funding, launch)
• Error Handling: Graceful degradation for Firebase/Solana failures with partial failure support

Data Layer

• Existing Models: Use WalletInfo, ScheduledFundingInfo, LaunchInfo, TokenHolding without changes
• Status Management: Automatic status updates based on balance thresholds (0.25 SOL = FUNDED)
• Field Updates: Automatic updates during refresh (first_funded_at, last_balance_sol, launch_count, updated_at)
• Token Data: SPL token holdings cached as List[TokenHolding] within wallet data

Web UI Integration

• Web UI Interface: User interface for wallet management operations with manual refresh controls. Not part of this epic but will consume orchestrator endpoints.
• Wallet List: Display all wallets with their current status and balances
• Cache Indicators: Display cache freshness and provide refresh triggers
• Token Display: Show SPL token holdings using TokenHolding model (name, ticker, balance, mint_address)

Implementation Strategy

API-First Approach: Enables parallel UI development

Phase 0: API Contract & Mock Implementation (Week 1 - Can start immediately)

• Define complete API specification with request/response models
• Create src/web_ui/routes/wallet_management_routes.py with mock responses for all 13 endpoints
• Integrate with existing FastAPI app in src/web_ui/main.py
• Generate OpenAPI documentation for UI team contract
• Deliverable: Functional API endpoints returning realistic mock data - enables UI development to start immediately

Phase 1: Core Integration (Week 2 - Parallel with UI development)

• Implement WalletManagementOrchestrator class coordinating existing services
• Wire up SimpleFirebaseService and SimpleSolanaService initialization with SOLANA_RPC_URL
• Implement basic cache-first logic (Firebase query → optional Solana refresh)
• Verify WalletInfo model fields support orchestrator requirements

Phase 2: API Integration (Week 3 - Gradual replacement of mocks)

• Replace mock endpoints with real orchestrator calls (gradual migration)
• Add manual refresh endpoints for SOL balance, token holdings, and funding transactions
• Implement funding schedule and launch tracking endpoints
• Implement error handling for Firebase vs Solana failures with UI-friendly error messages

Phase 3: Testing & Polish (Week 4)

• Integration tests between orchestrator and existing services
• End-to-end tests from UI through orchestrator to services
• Error handling validation and performance optimization
• Final API documentation updates

MVP Simplifications:

• No RPC backup or failover logic - direct SimpleSolanaService calls only
• No automatic refresh or real-time updates - manual triggers only
• Error handling focused on graceful degradation (Firebase failures vs Solana failures)
• Simple cache invalidation during refresh operations
• Use existing service interfaces without modification

Parallel Development Benefits:

• UI Team: Can start immediately with mock API endpoints (Week 1)
• Backend Team: Can focus on orchestrator implementation without blocking UI
• Integration: Gradual replacement of mocks ensures minimal disruption
• Timeline: Reduces overall timeline from 4-5 weeks sequential to 3-4 weeks parallel

Testing Approach:

• Unit tests for orchestrator coordination logic
• Integration tests verifying SimpleFirebaseService and SimpleSolanaService interaction
• End-to-end tests for complete cache-first workflows with manual refresh

Task Breakdown Preview

API-First Task Categories (Restructured for parallel development):

Phase 0: API Contract & Mocks (Week 1 - START IMMEDIATELY)

• API Models Definition: Create request/response models for all wallet management operations
• Mock Wallet Management Routes: Implement src/web_ui/routes/wallet_management_routes.py with 16 mock endpoints
• FastAPI Integration: Add wallet routes to existing src/web_ui/main.py app
• API Documentation: Generate OpenAPI/Swagger docs for UI team contract

Phase 1: Core Implementation (Week 2 - Parallel with UI)

• WalletInfo Model Validation: Verify existing WalletInfo includes required fields (first_funded_at, last_balance_sol, launch_count, updated_at)
• Core Orchestrator Implementation: Create WalletManagementOrchestrator class that coordinates SimpleFirebaseService and SimpleSolanaService
• Service Integration Layer: Wire up orchestrator with existing services using SOLANA_RPC_URL
• Cache Tracking: Add simple cache timestamp fields for data freshness (no wrapper models)

Phase 2: API Integration (Week 3 - Replace mocks gradually)

• Core Operations Integration: Replace mock wallet CRUD endpoints with orchestrator calls
• Refresh Operations Integration: Replace mock refresh endpoints with real Solana queries
• Portfolio & Analytics Integration: Replace mock portfolio endpoints with Firebase aggregations
• Funding & Launch Integration: Replace mock funding/launch endpoints with real operations
• Error Handling Implementation: UI-friendly error responses for Firebase vs Solana failures

Phase 3: Testing & Polish (Week 4)

• Integration Testing: Test orchestrator coordination between Firebase and Solana services
• End-to-End Validation: Complete workflow testing from UI to blockchain with token holdings
• Performance Optimization: Response time optimization and error handling refinement

Dependencies

External Dependencies:

• Firebase: Primary data storage and caching layer (existing)
• Solana Mainnet RPC: Blockchain data queries via SOLANA_RPC_URL
• FastAPI: Web framework for API endpoints (existing)

Internal Dependencies:

• Existing domain models: WalletInfo, ScheduledFundingInfo, LaunchInfo, TokenHolding (ready)
• SimpleFirebaseService: Concrete implementation of WalletsDataService (implemented)
• SimpleSolanaService: Concrete implementation of SolanaDataService with get_token_holdings() method (implemented)
• WalletsDataService interface: Abstract base class for Firebase operations (ready)
• SolanaDataService interface: Abstract base class for Solana operations (ready)
• Web UI framework: Frontend infrastructure for wallet management interface. Does not exist yet but will be implemented in the future

Integration Requirements:

• No integration with existing pump.fun launch code (standalone system)
• No integration with domain architecture Event → Processing → Execution pattern
• No integration with AI content generation workflows

Success Criteria (Technical)

Quality Gates:

• Graceful handling of Firebase and Solana service failures
• Partial failure support for independent data refresh (SOL balance, tokens, transactions)
• Zero data loss during manual refresh operations

Acceptance Criteria:

• Operations staff can view all wallets from cache
• Manual refresh updates cache with fresh blockchain data
• Cache freshness indicators show data age and refresh options

Estimated Effort

Overall Timeline: 3-4 weeks total (API-first parallel development)

• Phase 0 - API Contract & Mocks: 1 week (enables UI to start immediately)
• Phase 1 - Core Implementation: 1 week (parallel with UI development)
• Phase 2 - API Integration: 1 week (gradual mock replacement)
• Phase 3 - Integration Testing: 1 week

Resource Requirements:

• 1 Backend Developer (API mocks, orchestrator, integration)
• 1 Frontend Developer (can start immediately with mock APIs)
• Shared QA for integration testing

Parallel Development Benefits:

• Week 1: Backend creates mock APIs, UI starts development immediately
• Week 2-3: Backend builds orchestrator while UI uses mock APIs
• Week 4: Integration testing with both teams working on real endpoints
• Timeline Reduction: From 4-5 weeks sequential to 3-4 weeks parallel

Simplified MVP Scope:

• Leveraging existing SimpleFirebaseService and SimpleSolanaService
• No complex RPC failover or backup logic
• Manual refresh only (no automatic updates)
• API-first development enables independent UI development

Critical Path Items (API-First):

1. API mock implementation - Enables UI development to start immediately (Week 1)
2. Core orchestrator implementation - Coordinates existing services (Week 2)
3. Gradual mock replacement - Seamless integration without disrupting UI (Week 3)
4. Integration testing - Ensures end-to-end functionality (Week 4)

API Route Structure (Following existing FastAPI patterns):

# src/web_ui/routes/wallet_management_routes.py
router = APIRouter(prefix="/api/wallets", tags=["wallet-management"])

# Core Operations (5 endpoints)
GET    /api/wallets/                    # List all wallets with cache status
GET    /api/wallets/{wallet_address}    # Get single wallet with token holdings
POST   /api/wallets/                    # Create wallet entry in Firebase
PUT    /api/wallets/{wallet_address}    # Update wallet metadata
DELETE /api/wallets/{wallet_address}    # Remove wallet from cache

# Refresh Operations (2 endpoints)
POST   /api/wallets/{wallet_address}/refresh    # Refresh single wallet data
POST   /api/wallets/refresh-all               # Refresh all wallets (bulk)

# Funding Operations (3 endpoints)
GET    /api/wallets/funding/scheduled   # List scheduled funding operations
POST   /api/wallets/funding/schedule    # Schedule new funding
DELETE /api/wallets/funding/{schedule_id} # Cancel scheduled funding

# Launch Operations (3 endpoints)
GET    /api/wallets/launches/           # List all launch records
GET    /api/wallets/launches/{wallet_address} # Get wallet launch history
POST   /api/wallets/launches/record     # Record new launch

Risk Factors:

• Integration complexity between SimpleFirebaseService and SimpleSolanaService
• Solana RPC reliability without backup/failover (MVP simplicity)
• Coordination of cache invalidation during manual refresh operations

Stats

Total tasks: 12
Parallel tasks: 7 (can be worked on simultaneously)
Sequential tasks: 5 (have dependencies)
Estimated total effort: 80-100 hours (reduced with simplified models)

[Haydart]

✅ Epic completed - all tasks done