[{"_1":2,"_78":-5,"_79":-5},"loaderData",{"_3":4,"_7":8},"root",{"_5":6},"gaMeasurementId","G-LQYTSH5Y0M","routes/skill.$id",{"_9":10,"_52":53,"_71":-5,"_72":73,"_76":77},"skill",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":34,"_36":37,"_38":34,"_39":40,"_41":42,"_43":44,"_45":-5,"_46":-5,"_47":48,"_49":30,"_50":51},"id","d52932d5-62fa-47ef-bc95-efbd87937a87","title","vhybZ - System Architecture & Design","description","vhybZ is an AI-powered platform designed to help creators easily build and share interactive digital artifacts. This document outlines the system architecture, design decisions, and implementation details for the vhybZ backend and frontend components in this monorepo.","content","# vhybZ - System Architecture & Design\n\n## Overview\n\nvhybZ is an AI-powered platform designed to help creators easily build and share interactive digital artifacts. This document outlines the system architecture, design decisions, and implementation details for the vhybZ backend and frontend components in this monorepo.\n\n## Monorepo Architecture\n\n### Repository Structure\nThis monorepo contains:\n- **@server/** - Deno backend (Fresh 2.0 framework)\n- **@studio/** - React frontend (Vite + shadcn/ui)\n- **vhybZ Library** (External): Core AI/LLM logic (repo: https://github.com/vhybzOS/vhybZ)\n- **Mobile App** (Future): React Native app (repo: https://github.com/vhybzOS/RN-vhybZ)\n\n### Platform Integration\n- **@server/**: Data store, authentication, public hosting, analytics, artifact serving\n- **@studio/**: React UI layer, user experience, vhybZ library integration\n- **vhybZ Library**: LLM interactions, HTML generation, real-time preview logic\n- **Artifact Hosting**: Custom subdomains at `username.vhybz.com/artifact-name`\n\n## User Journey\n\n1. **Authentication**\n - User logs in via Google OAuth (handled by @server/)\n - Session established via secure, HTTP-only cookies\n\n2. **Artifact Creation**\n - @studio/ presents ChatGPT-like interface\n - User describes desired artifact in natural language\n - vhybZ library generates interactive HTML artifact\n - Artifact previews in real-time within @studio/\n\n3. **Iteration**\n - User provides feedback or new prompts in @studio/\n - vhybZ library refines artifact iteratively\n - Changes appear instantly in the @studio/ preview\n\n4. **Publishing**\n - User saves final artifact via @studio/\n - @server/ assigns URL: `username.vhybz.com/ArtifactName-slug`\n - Artifact becomes publicly accessible via @server/\n\n5. **Sharing**\n - User copies shareable link from @studio/\n - Others can view but not edit the artifact via @server/\n\n### Design Rationale\nBased on user interviews, we chose this design because:\n\n1. **For Creators**\n - Eliminates technical barriers (no coding required)\n - Natural language interface feels familiar (ChatGPT-like)\n - Instant visual feedback reduces iteration time\n - Professional hosting with custom URLs\n\n2. **For Viewers**\n - Clean, dedicated URLs for sharing\n - No login required to view artifacts\n - Mobile-responsive viewing experience\n\n3. **Technical Foundation**\n - Separate clients for web (@studio/) and mobile ensure optimal UX\n - Central backend (@server/) handles authentication and artifact storage\n - Subdomain-based routing for user content\n\n4. **Key Differentiators**\n - Focus on visual artifacts, not just text\n - Iterative refinement through conversation\n - Professional presentation without technical complexity\n\nThis design directly addresses the core needs identified in user interviews, particularly the desire for:\n- Faster content creation (Mani, Termeh)\n- Professional presentation (Julien, Hastia)\n- Easy sharing and showcasing (all users)\n- No technical expertise required (Hastia, Termeh)\n\n## Server Architecture (@server/)\n\n**Role**: Data store and API layer (does NOT handle AI/LLM interactions)\n\n### Technology Stack\n- **Runtime**: Deno 1.40+\n- **Web Framework**: Fresh 2.0\n- **Database**: MongoDB\n- **Authentication**: Google OAuth 2.0\n- **Package Management**: JSR (JavaScript Registry)\n- **Deployment**: Deno Deploy (planned)\n\n### Separation of Concerns\n- **@server/ Responsibilities**: User management, artifact storage, authentication, analytics, public hosting\n- **vhybZ Library Responsibilities**: LLM API calls, HTML generation, real-time preview logic\n- **@studio/ Responsibilities**: UI layer, imports vhybZ library for core functionality\n\n### Database Design (`database.ts`)\n\n#### Collections\n1. **Users**\n - `_id`: ObjectId (MongoDB)\n - `googleId`: string (Google's unique ID)\n - `email`: string (User's email)\n - `name`: string (User's display name)\n - `avatar`: string? (URL to user's avatar)\n - `createdAt`: Date\n - `updatedAt`: Date\n\n2. **Apps**\n - `_id`: ObjectId (MongoDB)\n - `userId`: ObjectId (Reference to Users._id)\n - `name`: string (App/Artifact name)\n - `content`: string (Serialized content/configuration)\n - `createdAt`: Date\n - `updatedAt`: Date\n\n#### Design Decisions\n- **Schema Validation**: Uses Zod for robust runtime type checking and validation\n- **Connection Management**: Implements singleton pattern for database connection\n- **Error Handling**: Comprehensive error handling with meaningful messages\n- **Environment Variables**: Centralized configuration with sensible defaults\n\n### API Design (`main.ts`)\n\n#### Authentication Flow\n1. **Google OAuth 2.0 Integration**\n - `/auth/google` - Initiates OAuth flow\n - `/auth/google/callback` - Handles OAuth callback and session creation\n - Uses secure, HTTP-only cookies for session management\n\n#### Middleware\n1. **Session Middleware**\n - Parses session cookies\n - Attaches user session to request context\n\n2. **Auth Middleware**\n - Protects routes requiring authentication\n - Returns 401 for unauthenticated requests\n\n#### API Endpoints (Data Storage Only)\n- `GET /api/me` - Get current user profile (protected)\n- `GET /api/conversations` - List user's conversations (protected)\n- `POST /api/conversations` - Store conversation data from frontend (protected)\n- `GET /api/artifacts` - List user's artifacts (protected)\n- `POST /api/artifacts` - Store artifact HTML from frontend (protected)\n- `PUT /api/artifacts/:id` - Update artifact with new HTML from frontend (protected)\n- `GET /api/artifacts/:id` - Get artifact details (public/private based on settings)\n- `POST /auth/logout` - Logout user\n\n**Note**: @server/ does NOT generate artifacts or call LLMs - it only stores data sent by @studio/ clients.\n\n## Studio Architecture (@studio/)\n\n**Role**: Web interface and vhybZ library integration\n\n### Technology Stack\n- **Framework**: React 19.1.0 with TypeScript for type safety\n- **Build System**: Vite 6.3.5 with hot module replacement and fast builds\n- **UI Framework**: shadcn/ui with Tailwind CSS (migrated from Material-UI)\n- **State Management**: React Context + Hooks pattern\n- **Routing**: React Router for single-page application navigation\n- **Development**: ESLint with React-specific rules and best practices\n\n### Application Structure\n```\nsrc/\n├── components/ # Reusable UI components\n│ ├── common/ # Shared components (Button, Modal, etc.)\n│ ├── chat/ # Chat interface components\n│ ├── artifacts/ # Artifact display and interaction\n│ └── layout/ # Layout and navigation components\n├── pages/ # Route-based page components\n│ ├── Dashboard/ # User dashboard and artifact gallery\n│ ├── Create/ # Artifact creation interface\n│ ├── Collaborate/ # Real-time collaboration features\n│ └── Profile/ # User profile and settings\n├── hooks/ # Custom React hooks\n│ ├── useAuth.ts # Authentication state management\n│ ├── useArtifacts.ts # Artifact CRUD operations\n│ └── useVhybZ.ts # vhybZ library integration\n├── services/ # External service integrations\n│ ├── api.ts # Backend API client (@server/ integration)\n│ ├── vhybz.ts # vhybZ library wrapper\n│ └── auth.ts # Authentication service\n├── utils/ # Shared utilities and helpers\n├── types/ # TypeScript type definitions\n├── contexts/ # React Context providers\n└── styles/ # Global styles and shadcn/ui themes\n```\n\n## Core Features Implementation\n\n### 1. ChatGPT-like Interface (@studio/)\n\n#### Conversation Component Architecture\n```typescript\ninterface ConversationProps {\n conversationId?: string;\n onArtifactGenerated: (artifact: Artifact) => void;\n}\n\nconst Conversation: React.FC = ({ \n conversationId, \n onArtifactGenerated \n}) => {\n const { createArtifact, isGenerating } = useVhybZ();\n const [messages, setMessages] = useState([]);\n const [inputValue, setInputValue] = useState('');\n \n const handleSubmit = async (prompt: string) => {\n const userMessage = { role: 'user', content: prompt };\n setMessages(prev => [...prev, userMessage]);\n \n try {\n const artifact = await createArtifact({\n prompt,\n conversationId,\n onUpdate: (update) => {\n // Show real-time generation progress\n setStreamingContent(update.html);\n }\n });\n \n const assistantMessage = { \n role: 'assistant', \n content: 'Artifact created successfully',\n artifact \n };\n setMessages(prev => [...prev, assistantMessage]);\n onArtifactGenerated(artifact);\n } catch (error) {\n // Handle generation errors gracefully\n showErrorMessage(error.message);\n }\n };\n \n return (\n \n \n \n \n );\n};\n```\n\n### 2. Real-time Artifact Preview (@studio/)\n\n#### Sandboxed Preview Component\n```typescript\ninterface ArtifactPreviewProps {\n content: string;\n isLoading?: boolean;\n onError?: (error: Error) => void;\n}\n\nconst ArtifactPreview: React.FC = ({ \n content, \n isLoading, \n onError \n}) => {\n const iframeRef = useRef(null);\n const [previewError, setPreviewError] = useState(null);\n \n useEffect(() => {\n if (!iframeRef.current || !content) return;\n \n try {\n const iframe = iframeRef.current;\n const doc = iframe.contentDocument || iframe.contentWindow?.document;\n \n if (doc) {\n // Clear previous content\n doc.open();\n \n // Inject security headers and sanitized content\n const sanitizedContent = sanitizeHTML(content);\n const wrappedContent = wrapWithSecurity(sanitizedContent);\n \n doc.write(wrappedContent);\n doc.close();\n \n setPreviewError(null);\n }\n } catch (error) {\n setPreviewError(error.message);\n onError?.(error);\n }\n }, [content, onError]);\n \n if (isLoading) {\n return ;\n }\n \n if (previewError) {\n return ;\n }\n \n return (\n \n \n \n );\n};\n```\n\n### 3. vhybZ Library Integration (@studio/)\n\n#### Custom Hook for Library Integration\n```typescript\nconst useVhybZ = () => {\n const { user, token } = useAuth();\n const [generator] = useState(() => {\n return new VhybZGenerator({\n apiEndpoint: process.env.REACT_APP_API_URL,\n authToken: token,\n clientType: 'web',\n options: {\n enableStreaming: true,\n enableSOUL: true,\n maxConcurrentGenerations: 3\n }\n });\n });\n \n const createArtifact = useCallback(async (options: {\n prompt: string;\n conversationId?: string;\n onUpdate?: (update: ArtifactUpdate) => void;\n }) => {\n return await generator.createArtifact({\n ...options,\n userContext: {\n userId: user?.id,\n preferences: user?.preferences,\n subscription: user?.subscription\n }\n });\n }, [generator, user]);\n \n const refineArtifact = useCallback(async (\n artifactId: string,\n refinementPrompt: string\n ) => {\n return await generator.refineArtifact(artifactId, refinementPrompt);\n }, [generator]);\n \n return {\n createArtifact,\n refineArtifact,\n isGenerating: generator.isGenerating,\n supportedTypes: generator.getSupportedArtifactTypes()\n };\n};\n```\n\n### 4. Backend API Integration (@studio/ ↔ @server/)\n\n#### API Client Service\n```typescript\nclass BackendAPIClient {\n private baseURL: string;\n private token: string | null = null;\n \n constructor(baseURL: string) {\n this.baseURL = baseURL;\n }\n \n setAuthToken(token: string) {\n this.token = token;\n }\n \n private async request(\n endpoint: string, \n options: RequestInit = {}\n ): Promise {\n const url = `${this.baseURL}${endpoint}`;\n const headers = {\n 'Content-Type': 'application/json',\n ...(this.token && { Authorization: `Bearer ${this.token}` }),\n ...options.headers\n };\n \n const response = await fetch(url, { ...options, headers });\n \n if (!response.ok) {\n throw new Error(`API Error: ${response.status} ${response.statusText}`);\n }\n \n return response.json();\n }\n \n // Artifact Management\n async saveArtifact(artifact: Artifact): Promise {\n const result = await this.request<{ id: string }>('/api/artifacts', {\n method: 'POST',\n body: JSON.stringify(artifact)\n });\n return result.id;\n }\n \n async getArtifacts(): Promise {\n return this.request('/api/artifacts');\n }\n \n async updateArtifact(id: string, changes: Partial): Promise {\n await this.request(`/api/artifacts/${id}`, {\n method: 'PUT',\n body: JSON.stringify(changes)\n });\n }\n \n // Conversation Management\n async saveConversation(conversation: Conversation): Promise {\n const result = await this.request<{ id: string }>('/api/conversations', {\n method: 'POST',\n body: JSON.stringify(conversation)\n });\n return result.id;\n }\n \n async getConversations(): Promise {\n return this.request('/api/conversations');\n }\n}\n```\n\n## Development Setup\n\n### Prerequisites\n- Deno 1.40+\n- Node.js 18+ (for @studio/)\n- MongoDB (local or Atlas)\n- Google OAuth credentials\n\n### Environment Variables\n```\n# @server/ environment\nMONGODB_URI=mongodb://localhost:27017\nMONGODB_DB_NAME=vhybZ\nGOOGLE_CLIENT_ID=your-client-id\nGOOGLE_CLIENT_SECRET=your-client-secret\n\n# @studio/ environment\nREACT_APP_API_URL=http://localhost:8000\nREACT_APP_ENVIRONMENT=development\n```\n\n### Running Locally\n```bash\n# Start @server/ (from server/ directory)\ncd server/\ndeno task dev\n\n# Start @studio/ (from studio/ directory)\ncd studio/\nnpm run dev\n\n# Or use monorepo approach\n# @server/ can be configured to also build and serve @studio/\n```\n\n### CRITICAL: Command Separation\n- **@server/**: Always use `deno` commands\n- **@studio/**: Always use `npm` commands\n- **NEVER mix**: Don't use npm in server/ or deno in studio/\n\n## Future Improvements\n\n### @server/ Enhancements\n- [ ] Rate limiting\n- [ ] API documentation (OpenAPI/Swagger)\n- [ ] Real-time collaboration (WebSockets)\n- [ ] File uploads (S3/GCS)\n- [ ] Analytics and monitoring\n\n### @studio/ Enhancements\n- [ ] Progressive Web App (PWA) support\n- [ ] Offline capabilities\n- [ ] Advanced editor features\n- [ ] Social features (likes, comments)\n- [ ] Performance optimization\n\n### Platform Integration\n- [ ] SOUL Agent management\n- [ ] Confidant bridge integration\n- [ ] Multi-agent coordination\n- [ ] Cross-device synchronization\n\n## Security Considerations\n- All routes are protected by default in @server/\n- CSRF protection for forms\n- Rate limiting for public endpoints\n- Input validation on all endpoints in @server/\n- Secure session management\n- Content sanitization in @studio/\n- Sandboxed artifact preview in @studio/\n\n## Monitoring & Observability\n- Error tracking (Sentry/LogRocket)\n- Performance monitoring\n- Usage analytics\n- Infrastructure monitoring\n\n## Cross-Repository Integration\n\nThis monorepo integrates with the broader vhybZ ecosystem:\n\n- **vhybZ Core Library**: Used by @studio/ for AI functionality\n- **Backend API**: @studio/ authenticates and persists data via @server/\n- **Mobile App**: Shares design patterns and user experience\n- **Platform Vision**: Enables \"vibe coding for the masses\" across all clients\n\n## Contributing\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n4. Ensure all tests pass in both @server/ and @studio/\n\n## License\nMIT\n\n---\nLast Updated: December 2025","sourceUrl","https://github.com/soverant/vhybZ/blob/6df72737fb5fa95e75f966e2713993b146294363/AGENTS.md","viewCount",0,"createdAt",["D",1768492590000],"status","published","skillType","prompt","difficulty",1,"timeToValueMin",5,"useCases","[]","inputs","outputFormat","markdown","dependencies","categoryId","b31af42c-ecda-40ee-a2ca-9845bad35f56","categoryName","Coding","categorySlug","coding","authorName","authorImage","hasAdditionalFiles",false,"fileCount","totalSizeBytes",16265,"relatedSkills",[54,60,65],{"_11":55,"_13":56,"_15":57,"_41":42,"_43":44,"_21":58,"_23":59,"_27":28,"_29":30,"_31":32,"_36":37},"b404ec38-bffb-4822-8916-4480ffb7cb0c","Nano Banana Pro","Agent skill for nano-banana-pro",6,["D",1767894033000],{"_11":61,"_13":62,"_15":63,"_41":42,"_43":44,"_21":32,"_23":64,"_27":28,"_29":30,"_31":32,"_36":37},"20883adf-3530-4398-a914-716aa3783689","Markdown Converter","Agent skill for markdown-converter",["D",1767894033000],{"_11":66,"_13":67,"_15":68,"_41":42,"_43":44,"_21":69,"_23":70,"_27":28,"_29":30,"_31":32,"_36":37},"525e6c82-58f2-4312-bfd2-c2972bb23e56","1password","Agent skill for 1password",3,["D",1767894032000],"session","userInteractions",{"_74":48,"_75":48},"liked","favorited","additionalFiles",[],"actionData","errors"]

vhybZ - System Architecture & Design

Prompt Playground

Fill Variables

Preview

Related Skills

Nano Banana Pro

Markdown Converter

1password