Web UI Architecture & Core Features

📋 Document Summary

What This Document Covers:

14-page web interface architecture
Orchestrator pattern with auto-initialization
Multi-layer storage strategy (ChromaDB, Firebase, Filesystem)
Core features (real-time updates, keyboard nav, AI editing)
Technology stack and integration patterns

Sections in This Document:

Architecture Overview
Orchestrator Pattern
Data Architecture
Frontend Architecture
Core Features
Technology Stack
Integration Patterns

Related Documentation:

→ WEB_UI_PAGES.md - Complete 14-page reference
→ API_ENDPOINTS.md - Complete API documentation
→ ../architecture/ORCHESTRATORS.md - Orchestrator details

Context Tags: #web-ui #architecture #orchestrators #real-time #keyboard-navigation

Architecture Overview

Three-Tier System Design

┌─────────────────────────────────────────────────────────┐
│                   Frontend Layer                        │
│  14 Pages • Vanilla JS • Modular Architecture           │
│  12 Shared Utilities • 13 Page Controllers              │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                   Backend Layer                         │
│  FastAPI • Async/Await • WebSocket Support              │
│  9 API Routers • Dependency Injection                   │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                   Orchestrator Layer                    │
│  6 Service Orchestrators • Auto-Initialization          │
│  Centralized Registry • Health Monitoring               │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                   Storage Layer                         │
│  ChromaDB (5 collections) • Firebase • Filesystem       │
└─────────────────────────────────────────────────────────┘

Orchestrator Pattern

Architecture Benefits

Auto-Initialization: All orchestrators start automatically on server startup via centralized registry
Health Monitoring: Continuous health checks with auto-recovery capabilities
Dependency Injection: Clean separation via dependencies.py with testability
Background Tasks: Managed long-running processes with proper cleanup
Singleton Pattern: Resource-efficient single instances per service
Centralized Registry: src/orchestrators/registry.py manages all orchestrator lifecycle

Six Core Orchestrators

Orchestrator	Purpose	Key Features
MemeStorageOrchestrator	File-based memecoin operations	Atomic file moves, cache invalidation, operation queue
GenerationOrchestrator	AI-powered generation	RAG workflow, session management, progress tracking
WalletsOrchestrator	Wallet portfolio management	Firebase cache, blockchain refresh, bulk operations
FundingOrchestrator	Automated SOL funding	Schedule execution, CEX integration, retry logic
LaunchConfigurationOrchestrator	Launch planning	Configuration CRUD, scheduling, validation
TrendOrchestrator	Real-time trend tracking	Reactive Firebase watchers, in-memory cache, prominence scoring

Auto-Initialization: All orchestrators start automatically via src/orchestrators/registry.py on server startup. See ../architecture/ORCHESTRATORS.md for implementation details.

Data Architecture

Multi-Layer Storage Strategy

Layer	Location	Purpose	Key Features
File System	`res/memecoins/`	Pending, approved, generated memecoins	JSON metadata + images (PNG/JPG)
ChromaDB	Vector DB	Semantic search + RAG retrieval	5 collections: image + 4 caption types (entity, context, visual, emotions), CLIP 768-dim embeddings
Firebase	Realtime DB	Wallets, launches, trends	Reactive watchers, configuration storage
Local Storage	Browser	Session state, UI preferences	Navigation history, cache

Data Flow Pipeline

Launch Detection → Pending Files → Manual Curation → Approved Files
                                                    ↓
                                            ChromaDB Vector DB
                                         (5 collections: image +
                                          4 caption types)
                                                    ↓
                                            AI Generation → Launch
                                                    ↑
                                                Degradation
                                            (back to Approved)

Frontend Architecture

14-Page Application Structure

Core Navigation Hub: /index.html (7-card dashboard)

Page Categories:

Data Management: Database, Generated, Pending, Approved
AI Generation: Generation interface with RAG workflow
Blockchain Operations: Wallets, Funding, Launches
Analytics: Meme Dashboard, Trend Tracking
Editing: Edit Memecoin (AI-powered metadata editor)

→ Detailed Page Reference: See WEB_UI_PAGES.md

JavaScript Modular Architecture

12 Shared Utility Modules (js/shared/):

api-client.js - Unified API client with error handling
memecoin-browser-base.js - Base class for memecoin browsing pages
modal-utils.js - Universal modal management
toast-manager.js - Toast notification system
navigation.js - Intelligent back navigation with history tracking
error-handling.js - Global error handling
data-display-utils.js - Data formatting utilities
form-utils.js, table-utils.js, timeout-utils.js, ui-helpers.js, utils.js

13 Page Controllers (js/pages/):

Each page has dedicated controller module
Controllers extend base classes for consistency
Event-driven architecture with lifecycle hooks

Standardized CSS Design System

Global Stylesheet (css/global.css):

Consistent address display classes across all 14 pages
.address-short - Truncated for tables (~160px with ellipsis)
.address-full - Full display for detail popups
.address-cell - Flexbox wrapper for address + copy button
.copy-address-btn - Standardized copy button with emoji (📋)

Core Features

1. Real-Time Integration

Blockchain Data:

Live wallet balance updates via Solana RPC
Optimistic UI updates with background reconciliation
WebSocket support for launch events (future)

Firebase Watchers:

Reactive trend data updates (TrendOrchestrator)
Auto-refresh every 60 seconds on trends page
Real-time funding schedule status changes

Progress Tracking:

AI generation progress with session management
Launch execution status monitoring
Funding operation state updates

2. Keyboard Navigation

Global Shortcuts:

Key	Action	Pages
`←/→`	Navigate items	Database, Pending, Approved, Generated
`Enter`	Primary action	Pending (approve), Generated (select)
`Backspace`	Delete/Reject	All browsers
`/`	Focus search	Database browser
`Ctrl+R`	Refresh data	All pages
`ESC`	Close modal	All modal dialogs
`E`	Edit memecoin	Database browser

3. AI-Powered Memecoin Editing

Complete Edit Workflow:

User selects memecoin in database browser
Provides natural language feedback: "The entity should be a cat, not a dog"
LLM generates edit proposal: Analyzes feedback, regenerates affected fields
User reviews/edits proposal: 5-minute cache window
Accepts proposal: Updates vector DB with new CLIP embeddings
Database refreshes: Shows updated memecoin

Key Endpoints:

POST /api/database/memecoins/{token_address}/edit - Generate proposal
POST /api/database/memecoins/{token_address}/accept - Apply changes

4. Toast Notification System

Four Notification Types:

Success: Green, auto-dismiss (3s)
Error: Red, manual dismiss required
Info: Blue, status updates
Warning: Yellow, important notices

Features:

Stackable notifications with z-index management
Automatic cleanup with timeout utilities
Responsive positioning (top-right corner)
Accessibility support (ARIA labels)

5. Universal Modal System

Design Characteristics:

Glassmorphism design (consistent across all pages)
Backdrop blur (10px) for focus
Keyboard support (Enter confirm, ESC cancel)
Mobile-optimized layouts
Prevent scroll-through behavior

Modal Types:

Confirmation dialogs (delete, approve)
Edit forms (AI-powered editing)
Detail views (trend details, wallet details)
Schedule creation (funding, launches)

6. Optimistic UI Updates

Pattern:

User initiates action (approve, delete, etc.)
UI updates immediately (remove from list, show toast)
API call executes in background
Success: Operation complete
Failure: Revert UI changes, show error toast

7. Transparent Pagination

Implementation:

Auto-load next page when current exhausted
No manual "Load More" buttons
Configurable page sizes per endpoint
Efficient handling of large datasets

Page Sizes:

Pending/Approved: 100 items/page (max 500)
Generated: 20 items/page (max 100)
Database: 200 items/page (no limit)

Technology Stack

Layer	Category	Technology	Purpose
Backend	Web Framework	FastAPI	Async API server with auto-docs
	Database	ChromaDB	Vector database (5 collections)
	Persistence	Firebase	Config storage with reactive watchers
	AI Services	OpenAI/Anthropic	LLM generation workflows
	Embeddings	Replicate CLIP	768-dim semantic embeddings
	Blockchain	Solana Web3.py	Wallet management, balance queries
Frontend	JavaScript	Vanilla ES6+	No framework dependencies
	Architecture	Modular pattern	12 shared utils + 13 page controllers
	Styling	CSS3	Standardized design system
	API Client	Fetch API	Unified error handling wrapper
	State Management	sessionStorage	Navigation history tracking

Integration Patterns

Pattern	Implementation	Key Features
Orchestrator Integration	FastAPI dependency injection via `Depends()`	Auto-wired orchestrators, testable, clean separation
API Client	Unified `APIClient` class in `api-client.js`	Centralized error handling, toast notifications, logging
Real-Time Updates	Firebase reactive watchers + TrendOrchestrator	Auto-refresh every 60s, event-driven updates
Caching Strategy	3-tier: File cache (MemeStorage), Firebase cache (Wallets), Proposal cache (5min TTL)	Reduces API/RPC calls, automatic cleanup

Example - Orchestrator Dependency Injection:

@router.get("/api/memecoins/pending")
async def get_pending_memecoins(
    orchestrator: MemeStorageOrchestrator = Depends(get_meme_storage_orchestrator)
):
    return APIResponse(success=True, data=await orchestrator.get_pending_memecoins())

File Organization

src/web_ui/
├── main.py                      # FastAPI app with orchestrator auto-startup
├── dependencies.py              # Orchestrator dependency injection
├── database.py                  # Legacy ChromaDB interface
├── api_models/                  # Pydantic API contracts (9 files: base, memecoin, generation, funding, launches, etc.)
├── api/                         # API routers (9 files: memecoin, database, generation, trends, wallets, funding, launches, etc.)
├── services/                    # Business logic (file_operations, memecoin, trend_image services)
└── static/
    ├── *.html                   # 14 single-page applications
    ├── css/                     # 7 stylesheets (global.css + page-specific)
    └── js/
        ├── shared/              # 12 reusable utilities (api-client, modal-utils, toast-manager, memecoin-browser-base, etc.)
        └── pages/               # 13 page controllers (database, generation, pending, approved, wallets, etc.)

Document Status: Complete Last Updated: October 15, 2025 Architecture Version: 14-page Web UI with orchestrator pattern

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Web UI Architecture & Core Features

📋 Document Summary

Architecture Overview

Three-Tier System Design

Orchestrator Pattern

Architecture Benefits

Six Core Orchestrators

Data Architecture

Multi-Layer Storage Strategy

Data Flow Pipeline

Frontend Architecture

14-Page Application Structure

JavaScript Modular Architecture

Standardized CSS Design System

Core Features

1. Real-Time Integration

2. Keyboard Navigation

3. AI-Powered Memecoin Editing

4. Toast Notification System

5. Universal Modal System

6. Optimistic UI Updates

7. Transparent Pagination

Technology Stack

Integration Patterns

File Organization

FilesExpand file tree

WEB_UI.md

Latest commit

History

WEB_UI.md

File metadata and controls

Web UI Architecture & Core Features

📋 Document Summary

Architecture Overview

Three-Tier System Design

Orchestrator Pattern

Architecture Benefits

Six Core Orchestrators

Data Architecture

Multi-Layer Storage Strategy

Data Flow Pipeline

Frontend Architecture

14-Page Application Structure

JavaScript Modular Architecture

Standardized CSS Design System

Core Features

1. Real-Time Integration

2. Keyboard Navigation

3. AI-Powered Memecoin Editing

4. Toast Notification System

5. Universal Modal System

6. Optimistic UI Updates

7. Transparent Pagination

Technology Stack

Integration Patterns

File Organization