BackPocket OS - Complete Documentation
Welcome to the BackPocket OS documentation hub. This folder contains comprehensive guides for all features, workflows, and system architecture.
š Quick Navigation
Core Features
- Email Automation - Smart email triage and draft generation
- Agentic RAG System - AI-powered document analysis with three specialized twins
- Blog & Content Generation - Narrative storytelling with AI
- Google Drive Integration - Sync and analyze Drive files
Workflows & Automation
- Social Media Posting Workflow - 4-step automation
- Content Calendar Management - 5-step planning system
- Analytics & Reporting - 4-step insights dashboard
- Newsletter Campaign Manager - 5-step distribution system
- Construction/Tradie Workflows - AI for trades
- Lead-to-Scope Extractor - Auto-extract client requirements
- Tradie Persona Follow-ups - Friendly quote follow-ups
- Site Note to Action Items - Voice-to-text automation
Setup & Configuration
- Installation & Setup - Get BackPocket running
- API Keys Configuration - Configure Google, OpenRouter, and other services
- Database Schema - SQLite tables and relationships
System Architecture
- Architecture Overview - System design and data flow
- AI Models & Routing - LLM selection and cost optimization
- Security & Privacy - Data handling and API security
Troubleshooting
- FAQ & Troubleshooting - Common issues and solutions
š„ Team Setup (new contributors ā marketing, law, research, engineering)
One-time setup, takes ~2 minutes:
git clone https://github.com/Sharv619/backpocket-mvp.git
cd backpocket-mvp
npm run setup
That installs MCP dependencies, creates the shared knowledge-bank table, and wires up the git hook that auto-logs every merge into main for audit (signed with your git author + commit SHA).
Then open OpenCode in the repo. Four MCP servers load automatically from .mcp.json:
| Server | Tools | Use for |
|---|---|---|
backpocket-leads | search / get / create leads | Lead intake work |
backpocket-quotes | create quote, templates, overdue list | Quoting + follow-ups |
backpocket-pipeline | pipeline summary, record payment | Ops / reporting |
backpocket-knowledge | save / search / list notes | Shared team knowledge bank |
Rule of thumb: anything worth referencing later ā marketing copy, legal notes, research findings ā drop it via the save_note tool in the knowledge bank, or just merge it into main and the post-merge hook captures it for you. Every entry is signed with your git identity so audits are trivial.
Full restructure rationale: docs/MCP_RESTRUCTURE_PLAN.md.
š Getting Started
1. Prerequisites
- Python 3.8+
- Google Cloud Project with APIs enabled
- OpenRouter API key
- Gmail OAuth configured
2. Quick Start
cd /home/lade/Hackathons/.git/backpocket-mvp
python3 -m uvicorn main:app --host 127.0.0.1 --port 8000
Visit: http://127.0.0.1:8000/static/index.html
3. Configure Your Sheet
- Go to
.envand findSPREADSHEET_ID - Copy your Google Sheet ID from the URL
- Paste into the
.envfile - Restart the server
š§ The Three Twins (AI Agents)
BackPocket uses three specialized AI agents that learn from your feedback:
| Twin | Purpose | Best For |
|---|---|---|
| Accountant | Financial & Tax | Invoices, GST, BAS, expense tracking |
| Auditor | Compliance & QA | Document review, verification, checks |
| Admin | Operations & Workflow | Email triage, scheduling, reminders |
Each twin:
- ā Learns from corrections (builds patterns)
- ā Accesses historical context via RAG
- ā Routes to cost-optimal AI model
- ā Generates professional responses
š° Cost Optimization
BackPocket intelligently routes API calls to minimize costs:
- Simple emails ā Template (free)
- Medium complexity ā Ollama/local (free)
- Complex requests ā OpenRouter (pay-per-use, but ~80% cheaper than raw API calls)
See AI Models & Routing for details.
š Key Concepts
RAG (Retrieval-Augmented Generation)
- Stores documents in ChromaDB vector database
- Retrieves relevant context before generating responses
- Enables AI to reference your business data
Learned Patterns
- Each correction becomes a learned pattern
- System automatically applies patterns to similar future emails
- Over time, twins get smarter without additional training
Vision Processing
- Analyze invoices, receipts, and documents
- Extract structured data from images
- Uses free OpenRouter vision models
š§ Common Tasks
Import Real Emails
python3 import_real_emails.py
Fetches your actual Gmail messages and populates the dashboard.
Sync Google Drive
Via the Dashboard:
- Go to š DRIVE section
- Enter your folder ID
- Click "Sync to RAG"
Or via API:
curl -X POST http://127.0.0.1:8000/api/drive/sync-to-rag \
-H "Content-Type: application/json" \
-d '{"folder_id":"YOUR_FOLDER_ID","twin_type":"admin"}'
Generate Blog Post
curl http://127.0.0.1:8000/api/blog/generate?title=My%20Story&theme=entrepreneurship
š Support
For detailed information on any topic, see the relevant documentation file in this folder.
Need help? Check TROUBLESHOOTING.md