The MagicSync Castle — Understanding Our Building Blocks
Welcome to the architecture behind MagicSync! Our project is organized as a monorepo with layer packages. Each layer has a special job!
🗃️ The Treasure Room — @local-monorepo/db
The Database Layer stores everything!
What It Does
- Stores all posts, users, business profiles, and settings
- Uses Drizzle ORM — a super organized librarian
- Uses Turso (libSQL) — fast and reliable storage with vector support
Superpowers
- Never forgets your data
- Super fast like a race car
- Keeps everything organized
- Native vector support for AI features
🔐 The Gatekeeper — @local-monorepo/auth
The Auth Layer is like the security guard at the castle entrance!
What It Does
- Checks who you are (login, registration)
- Keeps bad guys out
- Manages passwords and sessions
- Uses Better Auth — a super trustworthy security system
Superpowers
- Login and registration
- Session management
- Server protection
- Works with the Database to remember everyone
🎨 The Design Room — @local-monorepo/ui
The UI Layer makes everything look beautiful!
What It Does
- Makes all the buttons, colors, and layouts
- Wraps Nuxt UI v4 components with
Base-prefix - Uses Tailwind CSS — like having a magic paint box
Superpowers
- Pre-made components (BaseButton, BaseCard, etc.)
- Dark and light modes
- Smooth animations
- Works on all screen sizes
🤖 The Innovation Lab — @local-monorepo/ai-tools
The AI Tools Layer is where the magic happens!
What It Does
- Uses AI to help create content
- Generates ideas and improves posts
- Has a teleprompter for videos
- Analyzes your growth
Features
Growth Strategy Dashboard
- Today's/This Week/This Month to-do lists
- 5 golden rules always visible
- 7/30/90 day action plans
Content Pipeline
- Idea brainstorming
- Hook variations (4 proven types)
- AI Health Check
- Teleprompter with speed control
- Edit checklist
Data Analytics
- Input your post stats
- Get instant recommendations
🧠 The Brain Trust — @local-monorepo/agent
The Agent Layer is where MagicSync thinks, plans, and reviews content!
What It Does
- Runs the pi SDK in-process (no separate backend service)
- Powers the business chat with streaming tools
- Keeps one content board per business (ideas → review → approved → delivery)
- Runs the content chain: research → write → humanize → SEO/GEO/link checks
- Stores knowledge for retrieval (Turso-native vector search)
- Protects private data with fail-closed PII filtering
- Downloads video with the pinned yt-dlp + ffmpeg toolchain
Superpowers
- Human approval gates before anything is scheduled or published
- Server-owned tools with tenant isolation (model arguments never pick the business)
- Per-business model choice (OpenAI, Anthropic, Google, OpenRouter, DeepSeek, Ollama)
- Bring-your-own tool backends: ScrapeGraphAI key + optional Python tools service
🐍 The Toolsmith Annex — packages/python-tools
The Python Tools sidecar is optional and user-run.
What It Does
- Exposes Python-only tools over a small HTTP API (
/health,/tools,/tools/{name}/run) - Ships
fetch_textplus ScrapeGraphAI Python tools (scrapegraph_smartscraper,scrapegraph_searchscraper) - Is configured per user from AI settings → Tool backends; the agent calls it through
python_tools_*
🖼️ The Art Gallery — @local-monorepo/assets
The Assets Layer stores images, icons, and files!
What It Does
- Stores all images, icons, and static files
- Makes them available to every other layer
- Keeps everything organized
Superpowers
- One place for ALL your media
- Shared across the whole castle
- Fast loading
⏰ The Time Tower — @local-monorepo/scheduler
The Scheduler Layer posts things at the perfect time!
What It Does
- Decides WHEN to send your posts
- Manages a queue
- Talks to social media platforms
- Uses a calendar built on Nuxt UI for the visual calendar
Connected Platforms
- Facebook, Instagram
- Twitter/X
- Bluesky
- TikTok, YouTube, Threads
- Reddit, Dribbble, WordPress, Dev.to
📋 The Bulk Post Office — @local-monorepo/bulk-scheduler
The Bulk Scheduler Layer handles thousands of posts at once!
What It Does
- Reads CSV files
- Creates hundreds of posts instantly
- Perfect for planning big campaigns
Superpowers
- Upload a list of 500 posts in seconds
- CSV format (easy to create in Excel)
- Smart validation
🤝 The Connector — @local-monorepo/connect
The Connect Layer makes friends with other social platforms!
What It Does
- Handles OAuth ("Login with Facebook" buttons)
- Manages API connections to all platforms
- Stores access tokens securely
Superpowers
- One-click social connections
- Secure token storage
- Multi-platform support
📝 The Story Room — @local-monorepo/content
The Content Layer is where blog posts and stories live!
What It Does
- Uses Nuxt Content to manage static content
- Creates beautiful documentation
- Manages the knowledge base
Superpowers
- Markdown support
- Beautiful code highlighting
- Fast page loads
📧 The Message Bird — @local-monorepo/email
The Email Layer sends important emails!
What It Does
- Sends transactional emails
- Uses MJML for beautiful email templates
- Welcomes new users, resets passwords, and more
Email Types
- Welcome emails
- Password resets
- Notifications
- Post schedule alerts
🔧 The Tools Workshop — @local-monorepo/tools
The Tools Layer provides in-browser utilities!
What It Does
- Image editor (text over images)
- Video silence remover
- Social media preview generator
- Email preview generator
Superpowers
- Works entirely in browser
- No server required
- Instant results
🏰 The Main Castle — @local-monorepo/site
The Site Layer brings everything together!
What It Does
- Extends ALL other layers
- This is what users actually see and use
- The final product that makes magic happen
What It Includes
- Everything from every layer
- All the pages users visit
- The main application
📚 The Library — @local-monorepo/doc
The Documentation Layer is the rulebook and map!
What It Does
- Built with VitePress
- This very documentation you're reading
- Guides, tutorials, and references
📦 The Template Shop — @local-monorepo/content/templates
The Templates Layer has pre-made content formats!
What It Does
- Stores chat templates
- Variable templates for customization
- Makes creating posts faster
- Keeps your brand consistent
How They All Work Together
User visits the Site 🏰
↓
Auth checks who you are 🔐
↓
Database shows your data 🗃️
↓
AI helps create content 🤖
↓
Agent plans, researches, and drafts — humans approve the board 🧠
↓
Scheduler posts at the right time ⏰
↓
Connect talks to social platforms 🤝
↓
Email sends confirmation 📧
↓
Stats show how it went! 📊For Developers
If you're a developer wanting to contribute:
| Layer | Tech Stack |
|---|---|
| UI | Nuxt 4, Nuxt UI v4, Tailwind CSS |
| Auth | Better Auth, better-sqlite3 |
| DB | Drizzle ORM, Turso (LibSQL) |
| AI | pi SDK (in-process), AI SDK embeddings |
| Scraper | ScrapeGraphAI (scrapegraph-js) + raw-fetch fallback |
| Python tools | FastAPI sidecar (optional, user-run, port 8100) |
| Scheduler | Nuxt UI calendar, Platform APIs |
| MJML | |
| Content | Nuxt Content |
| Site | Nuxt 4 (extends all layers) |
Now you understand the MagicSync castle! Each room has a special job, and together they make the magic happen!
Ready to explore more? Check out our Installation Guide!