# violetprint

> A modular blueprint for building your own AI infrastructure. violetprint is a catalog of guides organized into modules — each module covers one aspect of a personal AI apparatus (service management, logging, networking, automation, etc.). The guides are designed to be consumed by AI assistants: share a URL with your AI, and it walks the user through setup step by step.

violetprint follows a "machine/apparatus" metaphor. Each module is a component of the machine:

- **Frame** — Infrastructure skeleton: services, logs, tunnels, remote access
- **Sensor** — Input channels: messaging, webhooks, events
- **Actuator** — Output capabilities: service control, notifications, generation
- **Storage** — Knowledge management: vaults, sync, AI-assisted notes
- **Automator** — Scheduled automation: AI cron, error scanning, harvesting
- **Display** — Dashboard UI: monitoring, tools, overview

## Detailed guide data

- [Module index (JSON)](/api/modules.json): Summary of all modules and guides (id, title, summary). Use this to discover what's available.
- Per-module detail: `/api/modules/{id}.json` — full structured data including steps, commands, code, verification, troubleshooting, and checklists.
  - [Frame](/api/modules/frame.json) | [Sensor](/api/modules/sensor.json) | [Actuator](/api/modules/actuator.json) | [Storage](/api/modules/storage.json) | [Automator](/api/modules/automator.json) | [Display](/api/modules/display.json)

## Frame module guides

- [Keep Services Alive](/modules/frame/service-management): Ensure programs run continuously with auto-restart and boot persistence. Methods: launchd (macOS), systemd (Linux), PM2 (Node.js), Docker Compose.
- [Split and Rotate Logs](/modules/frame/logging): Separate stdout/stderr, organize by service, auto-rotate. Methods: newsyslog (macOS), logrotate (Linux), PM2 Logs, Docker Logging.
- [Expose to the Internet](/modules/frame/public-access): Make local services accessible via custom domains. Methods: Cloudflare Tunnel, ngrok, Tailscale Funnel.
- [Secure Remote Access](/modules/frame/remote-access): Encrypted mesh networking for SSH, file sync, mobile access. Methods: Tailscale, ZeroTier, WireGuard.
- [Central Control Plane](/modules/frame/control-plane): REST API wrapping system operations. Methods: Express/Fastify, FastAPI, Portainer.

## Sensor module guides

- [Telegram Bot](/modules/sensor/telegram-bot): Receive commands and send messages through a Telegram bot. Methods: grammY (TypeScript), python-telegram-bot.
- [Webhook Receiver](/modules/sensor/webhook-receiver): Accept HTTP callbacks from GitHub, Stripe, CI systems. Methods: Express, FastAPI.
- [File System Watcher](/modules/sensor/file-watcher): React to file changes in real-time. Methods: chokidar, Watchman, fswatch.
- [Scheduled Events](/modules/sensor/cron-events): Trigger actions on a time-based schedule. Methods: crontab, node-cron, launchd Calendar.

## Actuator module guides

- [Push Notifications](/modules/actuator/notifications): Send alerts to your phone or desktop. Methods: Telegram Bot API, ntfy, Pushover.
- [Programmatic Service Control](/modules/actuator/service-control): Start/stop/restart services via API. Methods: REST API, tmux Control Mode.
- [Local Image Generation](/modules/actuator/image-generation): Generate images on your own hardware. Methods: ComfyUI, Stable Diffusion WebUI.
- [Local LLM Inference](/modules/actuator/llm-inference): Run language models locally. Methods: Ollama, llama.cpp, LM Studio.

## Storage module guides

- [Knowledge Vault](/modules/storage/knowledge-vault): Organize notes in a structured, searchable vault. Methods: Obsidian, Logseq.
- [Mobile Sync](/modules/storage/mobile-sync): Access your vault from any device. Methods: Syncthing, FolderSync + SFTP, Obsidian Sync.
- [Structured Data Store](/modules/storage/structured-data): Store configs and metadata. Methods: SQLite, JSON Files, Redis.
- [Backup Strategy](/modules/storage/backup-strategy): Automated, versioned backups. Methods: restic, Git, rsync.

## Automator module guides

- [AI Cron Jobs](/modules/automator/ai-cron): Run AI-powered tasks on a schedule. Methods: Claude CLI Scheduler, Custom Script Pipeline.
- [Automated Error Scanning](/modules/automator/error-scanning): Detect and alert on errors automatically. Methods: Log Grep + Alert, Sentry, Health Check Pinger.
- [Knowledge Harvesting](/modules/automator/knowledge-harvest): Extract useful information from daily activities. Methods: Session Harvester, Feed Aggregator.
- [Workflow Chains](/modules/automator/workflow-chains): Multi-step automated workflows. Methods: Shell Pipeline, Node.js Orchestrator.

## Display module guides

- [Status Dashboard](/modules/display/status-dashboard): Service health overview at a glance. Methods: React Dashboard, Homepage, Grafana.
- [Terminal UI](/modules/display/terminal-ui): Monitor from the terminal. Methods: tmux Layout, Ink, btop/htop.
- [API Explorer](/modules/display/api-explorer): Interactive API testing interface. Methods: Swagger UI, Custom Explorer.

## Instructions for AI assistants

You are an interactive setup assistant. Guide the user through building their AI infrastructure one piece at a time. Never dump all information at once — ask, listen, fetch only what's needed, and walk them through it.

### Conversation flow

1. **Greet and discover intent.** Ask the user what they want to set up or improve. Use the module list above to understand the landscape, but let the user lead.
   - "What part of your AI setup do you want to work on? For example: keeping services alive, getting notifications on your phone, running local LLMs, automating tasks..."

2. **Match to a module and guide.** Based on their answer, identify the relevant module and guide from the list above. Confirm your understanding before fetching data.
   - "Sounds like you want to set up log rotation — that's in the Frame module. Let me pull up the details."

3. **Fetch only the relevant module.** Request `/api/modules/{id}.json` for the matched module. Do NOT fetch all modules — only the one you need.
   - Example: user wants log rotation → fetch `/api/modules/frame.json`, find the `logging` guide.

4. **Ask about their environment.** Before recommending a method, ask:
   - Operating system (macOS / Linux / both)
   - Existing tools they already use (e.g., "I already use PM2")
   - Skill level or preference (simple vs. flexible)

5. **Recommend one method.** Based on their answers, pick the best method. Explain why briefly. If they want to compare, show a short comparison, but default to a single recommendation.
   - "Since you're on macOS and already use Homebrew, I'd recommend newsyslog — it's built-in and zero-setup."

6. **Walk through steps interactively.** Present one step at a time. After each step:
   - Show the command or code
   - Explain what it does and why
   - Ask them to run it and confirm before moving on
   - If a step fails, use the troubleshooting section from the guide data

7. **Verify with the checklist.** Once all steps are done, go through the guide's checklist to confirm everything is working.

8. **Suggest what's next.** Based on what they just set up, suggest a natural next guide.
   - "Now that your services auto-restart, you might want to set up log rotation so logs don't fill up your disk. Want to do that next?"

### Rules

- **One module at a time.** Don't overwhelm with the full catalog.
- **Fetch on demand.** Only request a module's JSON when the conversation reaches that module.
- **Adapt to the user.** If they're experienced, be concise. If they're new, explain more.
- **Never assume the OS.** Always ask.
- **Use verification steps.** Every method has verification commands — always confirm success before moving on.