Galaxy Flow System - Universe Architecture
Visual galaxy connections with flow logic, data routing, and conditional navigation
🌌 Galaxy Flow System - Universe Architecture
Executive Summary
The Breakthrough: Enable space-builders to visually connect galaxies (major platform areas) with:
- Navigation flows - User journey control
- Data pipelines - Pass data between galaxies
- Conditional routing - If/else logic for different user types
- Event broadcasting - Real-time updates across galaxies
- Singularity flows - Complex business logic on connections
This transforms our platform builder from "build pages" to "orchestrate complete user experiences".
🎯 The Vision
Current State: Static Hierarchy
Universe
└─ Galaxy A
└─ Galaxy B
└─ Galaxy C
Problem: No way to define HOW galaxies connect or communicate
New State: Dynamic Flow Network
Universe (Visual Flow Map)
┌─────────┐ ┌──────────┐ ┌─────────┐
│ Auth │───navigate──────▶│Dashboard │────if admin────▶│ Admin │
│ Galaxy │ │ Galaxy │ │ Panel │
└─────────┘ └──────────┘ └─────────┘
│ │ │
│ pass: user data │ event: cart updated │
▼ ▼ ▼
[flow logic] [realtime sync] [conditional]
Solution: Visual canvas where space-builders SEE and CONTROL the entire user journey!
🏗️ Architecture
System Components
┌──────────────────────────────────────────────────────────────┐
│ GALAXY FLOW SYSTEM │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌──────────────────────────┐ │
│ │ Galaxy Nodes │◄───────┤ UniversalModuleService │ │
│ │ (Modules) │ │ (Module Registry) │ │
│ │ │ │ │ │
│ │ - Inputs │ │ - Get module manifest │ │
│ │ - Outputs │ │ - Public actions │ │
│ │ - Actions │ │ - Event system │ │
│ └─────────────────┘ └──────────────────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Galaxy Connections Service │ │
│ │ │ │
│ │ - Navigation connections │ │
│ │ - Data flow connections │ │
│ │ - Event connections │ │
│ │ - Conditional routing │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Visual Canvas Component │ │
│ │ │ │
│ │ - SVG connection rendering │ │
│ │ - Drag-to-connect interface │ │
│ │ - Mode system (view/edit/connect/flow) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
│
│ Integration
▼
┌─────────────────────────────────────┐
│ Singularity Integration │
│ │
│ - Attach flows to connections │
│ - Logic blocks for data transform │
│ - Complex routing logic │
└─────────────────────────────────────┘
📐 Core Types
GalaxyNode
/**
* Represents a galaxy as a node in the flow canvas
* Derived from UniversalModule manifest
*/
export interface GalaxyNode {
// Identity
id: string;
galaxyId: string; // Reference to UniversalModule
name: string;
type: 'galaxy';
// Visual Position
position: { x: number; y: number };
size?: { width: number; height: number };
// Module Information
moduleManifest: ModuleManifest;
icon: string;
color?: string;
// Communication Interface
inputs: GalaxyInput[];
outputs: GalaxyOutput[];
publicActions: string[]; // From module manifest
// Status
isEntry?: boolean; // Entry point for users
isActive?: boolean; // Currently active
isDeployed?: boolean; // Deployed and live
// Configuration
config?: Record<string, any>;
// Metadata
createdAt: Date;
updatedAt: Date;
}
/**
* Galaxy input port
*/
export interface GalaxyInput {
name: string;
type: string; // TypeScript type (User, Product, string, etc.)
description?: string;
required: boolean;
defaultValue?: any;
// Validation
validation?: {
pattern?: string;
min?: number;
max?: number;
custom?: string; // Custom validation expression
};
}
/**
* Galaxy output port
*/
export interface GalaxyOutput {
name: string;
type: string;
description?: string;
// Output can be:
// - Data (passed to next galaxy)
// - Event (broadcast to listeners)
// - Navigation (trigger route change)
mode: 'data' | 'event' | 'navigation';
}
GalaxyConnection
/**
* Connection between galaxies with logic and data flow
*/
export interface GalaxyConnection {
// Identity
id: string;
universeId: string;
// Connection Points
sourceGalaxyId: string;
targetGalaxyId: string | '*'; // '*' = broadcast to all
// Connection Type
type: GalaxyConnectionType;
// Configuration (varies by type)
config: ConnectionConfig;
// Visual
color?: string;
label?: string;
// Status
enabled: boolean;
// Metadata
createdAt: Date;
updatedAt: Date;
}
export type GalaxyConnectionType =
| 'navigation' // User navigation between galaxies
| 'data-flow' // Pass data from source to target
| 'event' // Event broadcast
| 'conditional'; // Conditional routing
/**
* Connection configuration (union type based on connection type)
*/
export type ConnectionConfig =
| NavigationConfig
| DataFlowConfig
| EventConfig
| ConditionalConfig;
/**
* Navigation Connection
* Routes user from one galaxy to another
*/
export interface NavigationConfig {
type: 'navigation';
// What triggers navigation?
trigger: {
type: 'click' | 'hover' | 'timer' | 'custom-event' | 'programmatic';
// For click/hover - which element?
elementId?: string;
elementSelector?: string;
// For timer
delay?: number;
// For custom event
eventName?: string;
};
// Navigation options
navigationMode: 'push' | 'replace' | 'modal' | 'drawer';
// Pass query params?
queryParams?: Record<string, string>;
// Animation
transition?: {
type: 'fade' | 'slide' | 'zoom';
duration: number;
};
}
/**
* Data Flow Connection
* Passes data from source galaxy output to target galaxy input
*/
export interface DataFlowConfig {
type: 'data-flow';
// Data mapping
sourceOutput: string; // Output port name from source galaxy
targetInput: string; // Input port name for target galaxy
// Optional transformation
transform?: {
type: 'function' | 'flow';
// Simple function
function?: string; // JavaScript expression
// Complex flow (Singularity)
flowId?: string;
};
// Validation
validateTypes?: boolean; // Check type compatibility
// Error handling
onError?: {
action: 'log' | 'alert' | 'fallback';
fallbackValue?: any;
};
}
/**
* Event Connection
* Broadcasts events from source to target(s)
*/
export interface EventConfig {
type: 'event';
// Event details
eventName: string;
// Event trigger
trigger: {
type: 'output-change' | 'action-call' | 'lifecycle' | 'custom';
sourceOutput?: string; // For output-change
actionName?: string; // For action-call
lifecycleEvent?: 'start' | 'stop' | 'destroy'; // For lifecycle
customEvent?: string; // For custom
};
// Data to send with event
payload?: {
sourceOutput?: string; // Send output value
custom?: Record<string, any>; // Custom data
};
// Filtering
filter?: string; // JavaScript expression - only fire if true
// Options
debounce?: number; // Milliseconds
throttle?: number; // Milliseconds
}
/**
* Conditional Connection
* Routes to different galaxies based on conditions
*/
export interface ConditionalConfig {
type: 'conditional';
// Condition evaluation
condition: {
expression: string; // JavaScript expression
context: 'source-output' | 'user-data' | 'global-state' | 'custom';
};
// Routing
onTrue: string; // Galaxy ID if condition is true
onFalse: string; // Galaxy ID if condition is false
// Data passing
dataMapping?: {
sourceOutput: string;
targetInput: string;
};
// Fallback
onError?: string; // Galaxy ID if evaluation fails
}
🎨 Visual Canvas Component
Location
libs/libs-structural/space-map-lib/src/lib/components/galaxy-flow-canvas/
Key Features
1. Mode System
type CanvasMode = 'view' | 'edit' | 'connect' | 'flow';
// View Mode: Read-only, see connections
// Edit Mode: Move galaxies, edit properties
// Connect Mode: Drag to create connections
// Flow Mode: Attach singularity flows to connections
2. Connection Rendering
// SVG path generation for curved connections
function getConnectionPath(connection: GalaxyConnection): string {
const source = getNodePosition(connection.sourceGalaxyId);
const target = getNodePosition(connection.targetGalaxyId);
// Bezier curve for smooth connections
const controlPoint1 = {
x: source.x + (target.x - source.x) * 0.3,
y: source.y
};
const controlPoint2 = {
x: source.x + (target.x - source.x) * 0.7,
y: target.y
};
return `M ${source.x},${source.y}
C ${controlPoint1.x},${controlPoint1.y}
${controlPoint2.x},${controlPoint2.y}
${target.x},${target.y}`;
}
// Color by connection type
function getConnectionColor(type: GalaxyConnectionType): string {
switch(type) {
case 'navigation': return '#6366f1'; // Blue
case 'data-flow': return '#10b981'; // Green
case 'event': return '#f59e0b'; // Orange
case 'conditional': return '#8b5cf6'; // Purple
}
}
3. Drag-to-Connect Interface
// Similar to Singularity logic blocks
class GalaxyConnectionBuilder {
private sourceNode: GalaxyNode | null = null;
private sourcePort: GalaxyOutput | null = null;
startConnection(node: GalaxyNode, port: GalaxyOutput) {
this.sourceNode = node;
this.sourcePort = port;
// Show draggable connection line
}
completeConnection(targetNode: GalaxyNode, targetPort: GalaxyInput) {
if (!this.sourceNode || !this.sourcePort) return;
// Create connection
const connection: GalaxyConnection = {
id: generateId(),
sourceGalaxyId: this.sourceNode.id,
targetGalaxyId: targetNode.id,
type: this.determineConnectionType(this.sourcePort, targetPort),
// ... rest of config
};
// Save connection
this.connectionsService.create(connection);
}
}
🔄 Integration with Singularity
Attaching Flows to Connections
/**
* When connection needs complex logic, attach a Singularity flow
*/
interface FlowAttachment {
connectionId: string;
flowId: string;
// Flow inputs from source galaxy
inputMapping: {
sourceOutput: string;
flowInput: string;
}[];
// Flow outputs to target galaxy
outputMapping: {
flowOutput: string;
targetInput: string;
}[];
}
// Example: Add-to-cart connection with inventory check
const connection: GalaxyConnection = {
id: 'add-to-cart-conn',
sourceGalaxyId: 'products',
targetGalaxyId: 'cart',
type: 'data-flow',
config: {
type: 'data-flow',
sourceOutput: 'selectedProduct',
targetInput: 'product',
// Attach flow for complex logic
transform: {
type: 'flow',
flowId: 'add-to-cart-flow'
}
}
};
// The flow handles:
// 1. Check inventory availability
// 2. Validate product exists
// 3. Check user cart limits
// 4. Calculate pricing
// 5. Update cart count
// 6. Broadcast cart:updated event
Flow Builder Integration
// Open flow builder for connection
function editConnectionFlow(connection: GalaxyConnection) {
if (connection.config.type !== 'data-flow') return;
if (!connection.config.transform?.flowId) {
// Create new flow
const flowId = await singularityService.createFlow({
name: `${connection.label} Logic`,
description: `Flow logic for connection between galaxies`,
inputs: [
{
name: 'sourceData',
type: getOutputType(connection.sourceOutput)
}
],
outputs: [
{
name: 'targetData',
type: getInputType(connection.targetInput)
}
]
});
connection.config.transform.flowId = flowId;
}
// Navigate to flow builder
router.navigate(['/singularity/flow', connection.config.transform.flowId], {
queryParams: {
mode: 'connection-editor',
connectionId: connection.id
}
});
}
🔀 Connection Type Patterns
Pattern 1: Simple Navigation
Use Case: User clicks link to go to different area
const connection: GalaxyConnection = {
type: 'navigation',
sourceGalaxyId: 'home',
targetGalaxyId: 'products',
config: {
type: 'navigation',
trigger: {
type: 'click',
elementId: 'shop-now-button'
},
navigationMode: 'push'
}
};
Result: Clicking "Shop Now" button navigates to Products galaxy
Pattern 2: Data Handoff
Use Case: Pass selected item to detail view
const connection: GalaxyConnection = {
type: 'data-flow',
sourceGalaxyId: 'product-list',
targetGalaxyId: 'product-detail',
config: {
type: 'data-flow',
sourceOutput: 'selectedProduct',
targetInput: 'productData',
transform: {
type: 'function',
function: '(product) => ({ ...product, viewedAt: Date.now() })'
}
}
};
Result: Selected product flows to detail view with timestamp
Pattern 3: Conditional Routing
Use Case: Route users based on authentication status
const connection: GalaxyConnection = {
type: 'conditional',
sourceGalaxyId: 'auth',
targetGalaxyId: '', // Determined by condition
config: {
type: 'conditional',
condition: {
expression: 'user.isAuthenticated && user.role === "admin"',
context: 'source-output'
},
onTrue: 'admin-dashboard',
onFalse: 'user-dashboard',
onError: 'login-page'
}
};
Result: Admins go to admin dashboard, users to user dashboard, errors to login
Pattern 4: Event Broadcasting
Use Case: Update cart badge everywhere when cart changes
const connection: GalaxyConnection = {
type: 'event',
sourceGalaxyId: 'shopping-cart',
targetGalaxyId: '*', // Broadcast to all
config: {
type: 'event',
eventName: 'cart:updated',
trigger: {
type: 'output-change',
sourceOutput: 'cartCount'
},
payload: {
sourceOutput: 'cartCount'
},
debounce: 300 // Wait 300ms before firing
}
};
Result: Any change to cart count broadcasts event to all galaxies
🎮 User Experience
Space Builder Flow
Create Galaxies
- Add galaxy nodes to canvas
- Position visually
- Configure inputs/outputs from module manifest
Connect Galaxies
- Switch to "Connect" mode
- Drag from output port to input port
- System suggests connection type
- Configure connection details
Add Logic
- Click connection
- Choose "Add Logic"
- Either:
- Write simple JavaScript expression
- Create Singularity flow for complex logic
Test Flow
- Click "Test Journey"
- System simulates user path
- Shows data flowing through connections
- Highlights active galaxies
Deploy
- Click "Deploy Universe"
- System generates:
- Route configuration
- Navigation guards
- Data services
- Event handlers
🎯 Real-World Example: E-commerce Platform
Galaxies Setup
const ecommercePlatform = {
universeId: 'my-shop',
galaxies: [
{
id: 'auth',
name: 'Authentication',
icon: 'fas fa-lock',
isEntry: true,
outputs: [
{ name: 'user', type: 'User', mode: 'data' },
{ name: 'token', type: 'string', mode: 'data' }
]
},
{
id: 'home',
name: 'Home Page',
icon: 'fas fa-home',
inputs: [
{ name: 'user', type: 'User', required: false }
]
},
{
id: 'products',
name: 'Product Catalog',
icon: 'fas fa-shopping-bag',
outputs: [
{ name: 'selectedProduct', type: 'Product', mode: 'data' }
]
},
{
id: 'product-detail',
name: 'Product Detail',
icon: 'fas fa-info-circle',
inputs: [
{ name: 'productData', type: 'Product', required: true }
],
outputs: [
{ name: 'addedProduct', type: 'Product', mode: 'event' }
]
},
{
id: 'cart',
name: 'Shopping Cart',
icon: 'fas fa-shopping-cart',
inputs: [
{ name: 'product', type: 'Product', required: false }
],
outputs: [
{ name: 'cartCount', type: 'number', mode: 'event' },
{ name: 'cartTotal', type: 'number', mode: 'data' }
]
},
{
id: 'checkout',
name: 'Checkout',
icon: 'fas fa-credit-card',
inputs: [
{ name: 'cartData', type: 'Cart', required: true },
{ name: 'user', type: 'User', required: true }
]
}
],
connections: [
// 1. After login, go to home
{
id: 'login-to-home',
type: 'navigation',
sourceGalaxyId: 'auth',
targetGalaxyId: 'home',
config: {
type: 'navigation',
trigger: { type: 'programmatic' }, // After successful login
navigationMode: 'push'
}
},
// 2. Home to Products navigation
{
id: 'home-to-products',
type: 'navigation',
sourceGalaxyId: 'home',
targetGalaxyId: 'products',
config: {
type: 'navigation',
trigger: {
type: 'click',
elementSelector: '.shop-now-btn'
}
}
},
// 3. Product selection data flow
{
id: 'select-product',
type: 'data-flow',
sourceGalaxyId: 'products',
targetGalaxyId: 'product-detail',
config: {
type: 'data-flow',
sourceOutput: 'selectedProduct',
targetInput: 'productData'
}
},
// 4. Add to cart with complex logic
{
id: 'add-to-cart',
type: 'data-flow',
sourceGalaxyId: 'product-detail',
targetGalaxyId: 'cart',
config: {
type: 'data-flow',
sourceOutput: 'addedProduct',
targetInput: 'product',
transform: {
type: 'flow',
flowId: 'add-to-cart-validation-flow' // Singularity flow
}
}
},
// 5. Cart count broadcast
{
id: 'cart-update-broadcast',
type: 'event',
sourceGalaxyId: 'cart',
targetGalaxyId: '*',
config: {
type: 'event',
eventName: 'cart:updated',
trigger: {
type: 'output-change',
sourceOutput: 'cartCount'
},
payload: {
sourceOutput: 'cartCount'
},
debounce: 300
}
},
// 6. Conditional checkout (requires auth)
{
id: 'cart-to-checkout',
type: 'conditional',
sourceGalaxyId: 'cart',
targetGalaxyId: '',
config: {
type: 'conditional',
condition: {
expression: 'user && user.isAuthenticated',
context: 'global-state'
},
onTrue: 'checkout',
onFalse: 'auth' // Redirect to login first
}
}
]
};
📊 Benefits
For Space Builders
- Visual Understanding - SEE the entire user journey
- No Code Routing - Configure complex flows visually
- Reusable Patterns - Save common connection patterns
- Test Before Deploy - Simulate user paths
- Easy Modifications - Change flows without touching code
For End Users
- Seamless Experience - Smooth data flow between areas
- Fast Navigation - Optimized routing
- Consistent State - Data stays synchronized
- Personalized Paths - Conditional routing based on user
For Development
- Clear Architecture - Visual documentation of system
- Type Safety - Input/output types enforced
- Maintainable - Easy to update connections
- Testable - Can test paths in isolation
- Scalable - Add galaxies without breaking existing flow
🚀 Implementation Priority
Phase 1: Foundation (Week 1)
- Define core types (GalaxyNode, GalaxyConnection)
- Create GalaxyFlowCanvasComponent
- Implement basic SVG rendering
- Add galaxy node positioning
Phase 2: Connections (Week 2)
- Implement drag-to-connect
- Add connection type selector
- Create connection config panels
- Add connection validation
Phase 3: Logic Integration (Week 3)
- Integrate with Singularity
- Add flow attachment
- Implement conditional routing
- Add expression editor
Phase 4: Testing & Polish (Week 4)
- Add journey simulator
- Create connection templates
- Add export/import
- Performance optimization
🎓 Alignment with GoGrab-Modules
Module System Compatibility ✅
From @modules-arquitecture.md and @modules-monorepo-instructions.md:
Galaxies ARE UniversalModules ✅
- GalaxyNode wraps ModuleManifest
- Inputs/outputs from module manifest
- Public actions exposed as connection endpoints
BrowserModuleContract Integration ✅
- Module lifecycle hooks trigger connection events
- Module configuration affects galaxy behavior
- Module registration auto-creates galaxy nodes
Event System ✅
- Event connections use existing EventBusService
- Module events can trigger galaxy connections
- Cross-module communication via events
Type Safety ✅
- TypeScript types for inputs/outputs
- Validation at connection time
- Runtime type checking
Widget System Integration ✅
From @unified-widget-system.md:
Widgets Trigger Connections
- Button clicks navigate between galaxies
- Forms submit data to galaxy inputs
- Events broadcast to galaxy listeners
Widgets Display Galaxy Data
- Data binding to galaxy outputs
- Realtime updates from galaxy events
- Conditional rendering based on galaxy state
📝 Next Steps
- Create comprehensive types in
@libs-foundational/core-models - Build visual canvas in
space-map-lib - Integrate Singularity for flow attachment
- Add connection templates for common patterns
- Create examples for e-commerce, dashboard, admin platforms
- Document patterns for space-builders
- Test with real-world scenarios
This feature transforms our platform builder from a page/module creator into a COMPLETE USER EXPERIENCE ORCHESTRATOR. 🚀
Created: November 13, 2025
Status: 🎯 Revolutionary Breakthrough - Ready for Implementation
Priority: CRITICAL - This is the missing piece
Alignment: ✅ 100% Compatible with GoGrab-Modules Architecture