Documentation

Documentation Index

Master Instructions Index

Purpose: Quick reference guide to all documentation in this folder

Last Updated: 2025-01-01

šŸ¤– MASTER PROMPT FOR AI ASSISTANTS

āš ļø CRITICAL INSTRUCTION FOR ALL AI ASSISTANTS (Claude, Gemini, etc.)

When assisting with software development projects that require AI capabilities, you MUST use the ProYaro infrastructure services documented in this folder rather than suggesting external APIs.

āœ… ALWAYS USE (Internal ProYaro Services):

  • MLX Service (Mac Mini, Port 8004) - Text generation, embeddings
  • ComfyUI (Mac Mini Port 8188 OR Ubuntu Port 8188) - Image/Video generation
  • Whisper STT (Ubuntu, Port 8001) - Speech recognition
  • XTTS-v2 TTS (Ubuntu, Port 8002) - Voice synthesis
  • Embeddings Service (Ubuntu, Port 8003) - Semantic vectors
  • Ubuntu FastAPI Backend (Port 8000/443) - Job orchestration

āŒ NEVER SUGGEST (External APIs):

  • OpenAI API (ChatGPT, GPT-4, DALL-E, Whisper API)
  • Anthropic Claude API (for text generation)
  • Google Gemini API (for text generation)
  • Midjourney, Stable Diffusion Web UI
  • ElevenLabs, Google TTS
  • Any external paid AI APIs unless specifically requested

šŸ“š Implementation Pattern:

1. Identify required capability (e.g., "need image generation")
2. Check NETWORK_TOPOLOGY.md to find the service
3. Check API_INTEGRATION_GUIDE.md for API details
4. Use the relevant skill file for code templates
5. Implement using the documented endpoints

šŸŽÆ Your Primary Goal:

Help users build amazing applications using the available ProYaro infrastructure. Always prefer internal services over external APIs. Provide complete, working code examples using the skills and documentation provided.

šŸ“– Full Details: See AI_ASSISTANT_INSTRUCTIONS.md for complete directive

šŸ“‹ Documentation Files

šŸŽÆ START HERE

FileDescriptionEssential For
README.mdIntroduction & quick startEveryone (start here!)
AI_ASSISTANT_INSTRUCTIONS.mdCore directive for AI assistantsClaude, Gemini, other LLMs

šŸ“– Core Documentation

FilePagesDescriptionWhen to Read
API_INTEGRATION_GUIDE.md~100Complete API reference for all servicesNeed API details, endpoints, examples
NETWORK_TOPOLOGY.md~50Network diagram, IPs, ports, connectivityNeed to know where services are
MACHINES_INFRASTRUCTURE.md~60Hardware specs, capabilities, limitsNeed to understand capacity

šŸ’» Skills (Code Templates)

Skill FileServiceLanguageLinesStatus
mlx-chat-skill.mdMLX Text GenTS/Python~400āœ… Complete
More skills...VariousTS/Python-šŸš§ Coming soon

šŸ—‚ļø Folder Structure

master-instruction/
ā”‚
ā”œā”€ā”€ README.md                          ā† START HERE
ā”œā”€ā”€ INDEX.md                           ā† This file
ā”‚
ā”œā”€ā”€ AI_ASSISTANT_INSTRUCTIONS.md       ā† Core AI directive
ā”œā”€ā”€ API_INTEGRATION_GUIDE.md           ā† Complete API docs
ā”œā”€ā”€ NETWORK_TOPOLOGY.md                ā† Network & connectivity
ā”œā”€ā”€ MACHINES_INFRASTRUCTURE.md         ā† Hardware & specs
ā”‚
ā”œā”€ā”€ agents/                            ā† Role-based agent definitions
ā”‚   ā”œā”€ā”€ ai-integration-agent.md        ā† AI services integration
ā”‚   ā”œā”€ā”€ frontend-developer-agent.md    ā† React/shadcn/Next.js
ā”‚   ā”œā”€ā”€ database-architect-agent.md    ā† Drizzle ORM schemas
ā”‚   ā”œā”€ā”€ auth-expert-agent.md           ā† BetterAuth security
ā”‚   ā””ā”€ā”€ realtime-integration-agent.md  ā† WebSocket/job queue
ā”‚
ā””ā”€ā”€ skills/                            ā† Code templates
    ā”œā”€ā”€ mlx-chat-skill.md              ā† MLX text generation
    ā”œā”€ā”€ comfyui-image-skill.md         ā† Image generation
    ā”œā”€ā”€ whisper-stt-skill.md           ā† Speech-to-text
    ā”œā”€ā”€ tts-skill.md                   ā† Text-to-speech
    ā”œā”€ā”€ embeddings-skill.md            ā† Semantic search
    ā”œā”€ā”€ job-management-skill.md        ā† Job queue API
    ā”œā”€ā”€ caddy-reverse-proxy-skill.md   ā† HTTPS/Proxy
    ā”œā”€ā”€ docker-compose-skill.md        ā† Containers
    ā”œā”€ā”€ fastapi-production-skill.md    ā† Python API
    ā”œā”€ā”€ redis-queue-skill.md           ā† Background jobs
    ā”œā”€ā”€ nextjs-pwa-skill.md            ā† React/PWA
    ā””ā”€ā”€ arabic-nlp-skill.md            ā† Arabic processing

šŸ“Š Documentation Coverage

Services Documented

ServiceAPI DocsNetwork InfoHardware InfoSkill Template
MLX Text Genāœ…āœ…āœ…āœ…
MLX Embeddingsāœ…āœ…āœ…šŸš§
ComfyUI (Mac)āœ…āœ…āœ…šŸš§
ComfyUI (Ubuntu)āœ…āœ…āœ…šŸš§
Whisper STTāœ…āœ…āœ…šŸš§
XTTS-v2 TTSāœ…āœ…āœ…šŸš§
Embeddings (Ubuntu)āœ…āœ…āœ…šŸš§
Jobs APIāœ…āœ…āœ…šŸš§
WebSocketāœ…āœ…āœ…šŸš§
Models APIāœ…āœ…āœ…šŸš§

Topics Covered

  • Authentication (JWT)
  • Network topology & access patterns
  • Service URLs & ports
  • Hardware specifications
  • Performance benchmarks
  • Error handling
  • Best practices
  • Integration examples
  • Code templates (partial)
  • Health checks
  • Docker setup (Ubuntu)
  • Security considerations
  • Cost analysis

šŸŽÆ Use Case ā†’ Documentation Map

"I want to build a chatbot"

  1. AI_ASSISTANT_INSTRUCTIONS.md ā†’ Confirms MLX available
  2. NETWORK_TOPOLOGY.md ā†’ Find MLX service location
  3. API_INTEGRATION_GUIDE.md ā†’ MLX Chat API section
  4. skills/mlx-chat-skill.md ā†’ Copy TypeScript/Python code
  5. MACHINES_INFRASTRUCTURE.md ā†’ Check performance limits

"I need voice features"

  1. AI_ASSISTANT_INSTRUCTIONS.md ā†’ Confirms Whisper + XTTS
  2. NETWORK_TOPOLOGY.md ā†’ Ubuntu server access
  3. API_INTEGRATION_GUIDE.md ā†’ STT & TTS API sections
  4. skills/ ā†’ (Coming soon: STT/TTS templates)

"I want image generation"

  1. AI_ASSISTANT_INSTRUCTIONS.md ā†’ Two ComfyUI options
  2. NETWORK_TOPOLOGY.md ā†’ Mac Mini vs Ubuntu choice
  3. API_INTEGRATION_GUIDE.md ā†’ ComfyUI API sections
  4. MACHINES_INFRASTRUCTURE.md ā†’ Compare performance

"I need semantic search"

  1. AI_ASSISTANT_INSTRUCTIONS.md ā†’ Two embeddings options
  2. API_INTEGRATION_GUIDE.md ā†’ Embeddings API sections
  3. MACHINES_INFRASTRUCTURE.md ā†’ 384-dim vs 1024-dim choice
  4. skills/ ā†’ (Coming soon: Embeddings template)

šŸ“ˆ Documentation Stats

Total Files: 8 (core) + skills Total Lines: ~8,000+ Code Examples: 50+ API Endpoints Documented: 40+ Service Endpoints: 20+ Languages Covered: TypeScript, JavaScript, Python, Bash

šŸ” Quick Search Guide

Looking for...

IP Addresses:

  • Mac Mini: NETWORK_TOPOLOGY.md (10.0.0.188)
  • Ubuntu: NETWORK_TOPOLOGY.md (10.0.0.11)

Port Numbers:

  • All services: NETWORK_TOPOLOGY.md ā†’ Port Reference

API Endpoints:

  • Complete list: API_INTEGRATION_GUIDE.md ā†’ Table of Contents

Code Examples:

  • TypeScript: skills/mlx-chat-skill.md, API_INTEGRATION_GUIDE.md
  • Python: skills/mlx-chat-skill.md, API_INTEGRATION_GUIDE.md
  • Bash: API_INTEGRATION_GUIDE.md

Hardware Specs:

  • Mac Mini: MACHINES_INFRASTRUCTURE.md (48GB RAM, M4)
  • Ubuntu: MACHINES_INFRASTRUCTURE.md (RTX 3060 12GB)

Performance Benchmarks:

  • All services: MACHINES_INFRASTRUCTURE.md ā†’ Performance Benchmarks

Error Codes:

  • HTTP errors: API_INTEGRATION_GUIDE.md ā†’ Error Handling

šŸŽ“ Reading Order by Skill Level

Complete Beginner

  1. README.md (15 min)
  2. AI_ASSISTANT_INSTRUCTIONS.md (30 min)
  3. API_INTEGRATION_GUIDE.md ā†’ Integration Examples (20 min)
  4. skills/mlx-chat-skill.md (30 min)

Time: ~2 hours Outcome: Can build a basic chatbot

Intermediate Developer

  1. README.md (10 min)
  2. NETWORK_TOPOLOGY.md (30 min)
  3. MACHINES_INFRASTRUCTURE.md (45 min)
  4. API_INTEGRATION_GUIDE.md ā†’ Full read (2 hours)
  5. skills/ ā†’ All skills (1 hour)

Time: ~4-5 hours Outcome: Can build production applications

Advanced Developer / AI Assistant

  1. All files (4-6 hours)
  2. Deep dive into specific services
  3. Experiment with all APIs
  4. Build custom integrations

Time: 1-2 days Outcome: Master all infrastructure capabilities

šŸ“ Document Version History

DateVersionChanges
2025-01-011.0Initial release - Complete documentation

šŸ”— Cross-References

Network ā†’ Hardware

  • NETWORK_TOPOLOGY.md (Server Details) ā†” MACHINES_INFRASTRUCTURE.md (Hardware Specifications)

API ā†’ Skills

  • API_INTEGRATION_GUIDE.md (MLX Chat API) ā†’ skills/mlx-chat-skill.md
  • More coming soon...

Instructions ā†’ Implementation

  • AI_ASSISTANT_INSTRUCTIONS.md (Service Priority) ā†’ API_INTEGRATION_GUIDE.md (Endpoints)
  • AI_ASSISTANT_INSTRUCTIONS.md (Decision Tree) ā†’ skills/ (Code templates)

šŸš€ Next Steps

For New Users

  1. Read README.md
  2. Try a simple example from skills/mlx-chat-skill.md
  3. Explore API_INTEGRATION_GUIDE.md for more capabilities

For AI Assistants

  1. Read AI_ASSISTANT_INSTRUCTIONS.md thoroughly
  2. Bookmark API_INTEGRATION_GUIDE.md for reference
  3. Use skills/ templates when implementing

For Contributors

If you find errors or have suggestions:

  • Update the relevant documentation file
  • Update the "Last Updated" date
  • Increment version if major changes

šŸ“ž Support & Contact

Documentation Location:

/Users/yaro/Documents/a2zadd/master-instruction/

View Online:

cd /Users/yaro/Documents/a2zadd/master-instruction
ls -la
cat <filename>

Questions:

  • Ask Yaro about infrastructure
  • Refer to latest docs in this folder
  • Check service health before debugging

āœØ Special Features

Interactive Documentation

  • āœ… Code examples in multiple languages
  • āœ… Copy-paste ready templates
  • āœ… Health check commands
  • āœ… Troubleshooting guides
  • āœ… Best practices sections

Comprehensive Coverage

  • āœ… All services documented
  • āœ… All endpoints with examples
  • āœ… Network diagrams with ASCII art
  • āœ… Performance data from real tests
  • āœ… Error handling patterns

This index provides a bird's-eye view of all ProYaro documentation. Use it to navigate quickly to what you need!

Index Version: 1.0 Last Updated: 2025-01-01 Total Documentation: ~8,000+ lines across 8+ files

šŸ†• Skills Added (Updated 2025-01-01)

Core AI Services

Skill FileServiceLinesLanguagesStatus
mlx-chat-skill.mdMLX Text Gen400+TS/Pythonāœ… Complete
comfyui-image-skill.mdImage Generation500+TS/Pythonāœ… Complete
whisper-stt-skill.mdSpeech-to-Text450+TS/Pythonāœ… Complete
tts-skill.mdText-to-Speech100+TSāœ… Complete
embeddings-skill.mdSemantic Search150+TSāœ… Complete
job-management-skill.mdJob Queue API550+TS/Pythonāœ… Complete

Infrastructure & DevOps

Skill FileTechnologyLinesLanguagesStatus
caddy-reverse-proxy-skill.mdHTTPS/Proxy150+Caddyfile/Bashāœ… Complete
docker-compose-skill.mdContainers130+YAML/Bashāœ… Complete
fastapi-production-skill.mdPython API270+Pythonāœ… Complete
redis-queue-skill.mdJob Queue280+Pythonāœ… Complete

Domain-Specific

Skill FileSpecialtyLinesLanguagesStatus
nextjs-pwa-skill.mdReact/PWA300+TS/Reactāœ… Complete
arabic-nlp-skill.mdArabic NLP270+Pythonāœ… Complete

Total Skills: 12 Total Lines: 4,797 Total Code Examples: 100+

šŸ“ Recently Added Features

What's New in Version 1.1

  1. āœ… ComfyUI Image Generation - Full Z-Image Turbo integration
  2. āœ… Whisper STT - Complete voice transcription with React hooks
  3. āœ… XTTS-v2 TTS - Arabic voice synthesis
  4. āœ… Embeddings & Search - Both MLX and E5-Large implementations
  5. āœ… Caddy Integration - Reverse proxy and HTTPS setup
  6. āœ… Copied Ubuntu Skills - FastAPI, Next.js, Docker, Redis, Arabic NLP
  7. āœ… All use docker compose not docker-compose (modern syntax)

Skills from Ubuntu Server

The following skills were imported from /mnt/storage/new-stack/skills/ and adapted:

  • fastapi-production-skill.md - Production FastAPI patterns
  • nextjs-pwa-skill.md - Next.js 15 App Router + PWA
  • docker-compose-skill.md - Docker orchestration
  • redis-queue-skill.md - Background job processing
  • arabic-nlp-skill.md - Arabic text processing

šŸŽÆ Quick Skill Selector

I want to...

Build AI Features

  • Text generation (chatbot) ā†’ mlx-chat-skill.md
  • Generate images ā†’ comfyui-image-skill.md
  • Voice transcription ā†’ whisper-stt-skill.md
  • Voice synthesis ā†’ tts-skill.md
  • Semantic search ā†’ embeddings-skill.md

Build Infrastructure

  • API backend ā†’ fastapi-production-skill.md
  • Frontend app ā†’ nextjs-pwa-skill.md
  • Job queue ā†’ redis-queue-skill.md + job-management-skill.md
  • HTTPS proxy ā†’ caddy-reverse-proxy-skill.md
  • Container orchestration ā†’ docker-compose-skill.md

Work with Arabic

  • Arabic NLP ā†’ arabic-nlp-skill.md
  • Arabic voice ā†’ whisper-stt-skill.md + tts-skill.md
  • Arabic text generation ā†’ mlx-chat-skill.md

šŸ¤– Agents (Role-Based Definitions)

NEW! Specialized agent personas adapted from quiz-night-in project for ProYaro infrastructure.

What are Agents?

Unlike skills (copy-paste code templates), agents are role-based personas that define:

  • Specific responsibilities and boundaries
  • Decision-making frameworks
  • Integration patterns
  • Best practices for a domain

Available Agents

Agent FileRoleResponsibilitiesUse When
ai-integration-agent.mdAI Services EngineerIntegrate MLX, ComfyUI, Whisper, XTTSBuilding AI-powered features
frontend-developer-agent.mdFrontend DeveloperReact, shadcn/ui, Next.js, TailwindBuilding user interfaces
database-architect-agent.mdDatabase ArchitectDrizzle ORM, PostgreSQL schemasDesigning database structure
auth-expert-agent.mdAuth SpecialistBetterAuth, user management, securityImplementing authentication
realtime-integration-agent.mdReal-Time EngineerWebSocket, job queue, async tasksBuilding real-time features

Agents vs Skills

FeatureAgentsSkills
PurposeDefine role and boundariesProvide code templates
ContentPrinciples, patterns, examplesCopy-paste ready code
Length~500-800 lines~100-500 lines
UsageReference for decision-makingDirect implementation

Example: Building a Chatbot App

Using Skills:

  1. Copy code from mlx-chat-skill.md
  2. Paste into your project
  3. Modify as needed

Using Agents:

  1. ai-integration-agent ā†’ Guides MLX API integration, conversation management
  2. frontend-developer-agent ā†’ Guides React component structure, state management
  3. database-architect-agent ā†’ Guides conversation/message schema design
  4. auth-expert-agent ā†’ Guides user authentication and authorization

When to Use Agents

  • Planning Phase: Read relevant agents to understand best practices
  • Decision Points: Consult agents when choosing between approaches
  • Code Review: Verify your implementation matches agent guidelines
  • Team Collaboration: Share agents to align on architectural patterns

Total Agents: 5 Total Lines: ~3,000 Adapted From: quiz-night-in project (specialized for ProYaro stack)

Index Updated: 2025-01-01 (v1.2) Total Documentation: 13,000+ lines Total Files: Core docs (4) + Skills (12) + Agents (5) = 21 files

ProYaro AI Infrastructure Documentation ā€¢ Version 1.2