MOOD MNKY Ecosystem Blueprint
This blueprint provides a comprehensive overview of the MOOD MNKY ecosystem architecture, component relationships, and integration points. It serves as a reference for understanding how our physical products, digital platforms, AI agents, and community elements work together.
Ecosystem Architecture Overview
The MOOD MNKY ecosystem is designed as an integrated network of physical and digital experiences, supported by a robust technical architecture and AI-driven personalization. The mood-mnky-command monorepo implements the core digital platform as a single Next.js app.Source of truth: The app (
apps/web) and its Supabase data (e.g. main_landing_*, agent_profiles, fragrance_oils) are the implementation source of truth. This blueprint and other mnky-docs reflect the current app structure and routes. See Systems Architecture for routes and data sources.Current Implementation (mood-mnky-command)
- MNKY VERSE: Web portal (storefront, blog, agents, gamification) at
/verse - The Dojo: Private hub (XP, quests, Blending Lab, chat) at
/dojo - MNKY LABZ: Admin dashboard (formulas, oils, Shopify Admin) at
/ - Shopify: Liquid theme and app extension link to the app
Core System Components
Physical Product Ecosystem
Custom Fragrance System
The foundation of our personalized sensory experience, enabling bespoke scent creation
Bath & Body Products
Self-care essentials with personalized formulations and sensory elements
Home Ambiance
Products that transform living spaces into personalized sensory environments
Physical Product Integration Points
Physical Product Integration Points
- Digital-Physical Bridge: QR codes, NFC tags, and other technologies that connect physical products to digital experiences
- Formulation Database: System that stores custom formulations and enables reproduction
- Production Systems: Manufacturing and fulfillment processes for custom products
- Quality Assurance: Testing and validation systems for consistent product experiences
- Sustainable Materials: Environmentally responsible packaging and ingredients
Digital Platform Architecture
MNKY VERSE
Web experiential portal—storefront, blog, agents, gamification, community.
- Shopify Storefront API (products, cart)
- Verse blog (Supabase, Notion sync)
- AI agents directory & chat
- XP, quests, manga, UGC
- Fragrance tools (wheel, oils, glossary)
The Dojo
Members’ private hub—authenticated space for preferences and crafting.
- XP & level display
- Quests & quick actions
- Blending Lab & saved blends
- MNKY CHAT (Flowise)
- Preferences (default agent)
MNKY LABZ
Admin dashboard and command center for operations.
- Formulas, fragrance oils, glossary
- Shopify Admin integration
- Notion sync
- CODE MNKY assistant
- Platform tools (SQL, Flowise)
Technical Architecture
Technical Architecture
The MOOD MNKY digital platform (mood-mnky-command) is built on:
- Frontend: Next.js 14+ with App Router, TypeScript, shadcn/ui, Tailwind CSS
- E-commerce: Hydrogen React, Shopify Storefront API (not Remix Hydrogen)
- Backend: Supabase (PostgreSQL, Auth, Realtime, Storage)
- Integrations: Shopify Admin API, Notion, Flowise, OpenAI
- Hosting: Vercel (Next.js app); Shopify (theme + app extension)
Agent System
The intelligent agent system forms the core of our personalized assistance, content creation, and technical support capabilities:Agent Architecture
MOOD MNKY Agent
Customer experience specialist focusing on personalization, product guidance, and relationship building.
CODE MNKY Agent
Technical expert handling development, infrastructure, and technical documentation needs.
SAGE MNKY Agent
Knowledge specialist creating educational content, guiding learning, and facilitating community interactions.
Agent Integration Points
Agent Integration Points
- Web Platform Integration: Embedded chat interfaces, contextual assistance, and proactive suggestions
- Mobile Integration: Native agent interfaces with voice and visual input capabilities
- Dojo Integration: Learning guidance, content creation, and progress assessment
- E-commerce Integration: Product recommendations, custom product configuration, and order support
- Community Integration: Discussion moderation, content curation, and engagement facilitation
- API Access: External service access for task execution and data retrieval
Core Services
The backbone of the MOOD MNKY ecosystem consists of several critical services:| Service | Primary Function | Key Components | Integration Points |
|---|---|---|---|
| Personalization Engine | Creates tailored experiences based on user preferences, behavior, and context | Preference Graph, Recommendation System, Context Manager, Behavioral Analytics | All customer-facing interfaces, Agent System, Product Creation |
| E-commerce Services | Manages product catalog, inventory, orders, and customer accounts | Shopify Integration, Custom Product Builder, Order Management, Subscription System | Web Platform, Mobile App, Personalization Engine, Analytics |
| Memory System | Stores and retrieves contextual information about users and interactions | Vector Database, Conversation Memory, User Preferences, Interaction History | Agent System, Personalization Engine, Content Delivery |
| Analytics Engine | Collects, processes, and visualizes data for business intelligence | Event Tracking, Data Warehouse, Visualization Tools, Machine Learning Models | All platform components, Executive Dashboard, Optimization Tools |
| Content Management | Organizes, delivers, and personalizes content across the ecosystem | Content Repository, Delivery Network, Personalization Rules, Creation Tools | Dojo, Web Platform, Mobile App, Community |
Community Platform
The community platform connects members, facilitates engagement, and enables collaborative creation:Community Hub
Central gathering space for members to connect, share, and collaborate.
- Discussion forums
- Member profiles
- Activity feeds
- Event management
- Resource sharing
Token Economy
System that rewards engagement and enables value exchange in the community.
- Token earning mechanisms
- Redemption marketplace
- Value exchange system
- Status and recognition
- Engagement incentives
Data Architecture
The MOOD MNKY ecosystem is built on a sophisticated data architecture that enables personalization, analytics, and seamless experiences:Data Flow Architecture
Data Models
Data Models
The MOOD MNKY ecosystem uses several core data models:
- User Profile Model: Comprehensive representation of member preferences, history, and relationships
- Product Model: Detailed product information including composition, attributes, and relationships
- Content Model: Structured representation of educational and community content
- Interaction Model: Record of user engagements across all touchpoints
- Memory Model: Contextual information for personalized experiences
- Transaction Model: Record of economic activity including purchases and token transactions
Data Privacy and Security
Data Privacy and Security
Our approach to data privacy and security includes:
- Privacy by Design: Built-in privacy considerations at every stage
- Consent Management: Granular user control over data usage
- Data Minimization: Collecting only what’s necessary
- Secure Storage: Encryption at rest and in transit
- Access Controls: Role-based access with least privilege
- Retention Policies: Clear timelines for data usage and deletion
- Compliance Framework: Adherence to regulations including GDPR and CCPA
Integration Points and APIs
API Architecture
External APIs
Interfaces for third-party integration with the MOOD MNKY ecosystem:
- Shopify Storefront API
- Shopify Admin API
- User Management API
- Content Access API
- Analytics API
- Agent Interaction API
Internal APIs
Service-to-service communication within the ecosystem:
- Personalization Service API
- Memory System API
- Agent Orchestration API
- Token Economy API
- Analytics Service API
- Content Management API
Integration Patterns
| Pattern | Use Cases | Implementation |
|---|---|---|
| Event-Driven Architecture | Real-time updates, system notifications, activity tracking | Event bus, webhooks, Supabase real-time subscriptions |
| RESTful APIs | CRUD operations, resource management, simple integrations | Standard HTTP methods, consistent endpoints, proper status codes |
| GraphQL | Complex data requirements, flexible queries, reduced network load | Apollo Server, type definitions, resolvers |
| Webhook Notifications | External system notifications, e-commerce events, async processing | Subscription endpoints, verification, retry logic |
| Batch Processing | Analytics, reporting, bulk operations | Scheduled jobs, ETL processes, data pipelines |
Ecosystem Experience Flows
Core User Journeys
- Discovery & Onboarding
- Product Creation
- Learning Journey
- Community Engagement
Technical Implementation Reference
Technology Stack
Frontend Technologies
- Next.js with App Router
- TypeScript
- Tailwind CSS
- ShadCN UI components
- React Query
- Zustand for state management
Backend Technologies
- Supabase (PostgreSQL)
- Serverless Functions
- Edge Functions
- Node.js services
- GraphQL (where appropriate)
- Redis for caching
AI & Data Technologies
- LLM integration
- Vector databases
- Embedding models
- Data ETL pipelines
- Analytics platforms
- Machine learning frameworks
Development Infrastructure
Monorepo Structure
Turborepo-based monorepo (mood-mnky-command):
- apps/web - Single Next.js app (MNKY VERSE + Dojo + LABZ)
- Shopify/theme - Liquid theme
- extensions/ - Theme app extension
- supabase/ - Migrations and Edge Functions
- mnky-docs/ - Mintlify documentation
DevOps Pipeline
CI/CD and hosting:
- GitHub Actions for CI
- Vercel for Next.js deployment
- Shopify for theme and store
- Supabase for database and auth
Implementation Guidelines
Key Architecture Principles
Design Principles
- Privacy by Design: Privacy considerations built into every component
- Modularity: Clear boundaries between components for independent evolution
- Composability: Building blocks that can be combined in various ways
- Scalability: Systems that grow efficiently with user base and features
- Resilience: Fault tolerance and graceful degradation
- Accessibility: Inclusive design for all users
Implementation Guidelines
- API-First Development: Define interfaces before implementation
- Event-Driven Architecture: Loose coupling through events
- Progressive Enhancement: Core functionality first, enhancements after
- Performance Budgets: Strict limits on size and speed
- Continuous Optimization: Regular performance review and improvement
- Documentation as Code: Documentation maintained alongside codebase
Related Resources
- Ecosystem Roadmap for the strategic evolution timeline
- Technical Standards for implementation details
- API Documentation for interface specifications