JARGS CORMARK — Agentic AI Personal Assistant

A production-grade, WhatsApp-based agentic AI personal assistant and digital secretary. Orchestrated with CrewAI multi-agent flows and executed via OpenClaw skill modules.

What Is This?

JARGS CORMARK turns WhatsApp into an intelligent assistant capable of:

• Setting reminders and scheduling follow-ups
• Reading, creating, updating, and deleting Google Calendar events
• Conducting live web research and generating PDF reports
• Creating social media content (captions, design briefs, carousels)
• Managing tasks in your Notion workspace
• Transcribing voice messages and acting on them
• Gating high-stakes actions (send message, post publicly) behind explicit confirmation

The entire experience is conversational — the user sends a WhatsApp message; the assistant routes it to the right agent, executes the action at the appropriate autonomy level, and replies.

Tech Stack

| Layer | Technology | |---|---| | Backend framework | FastAPI + Uvicorn | | Agent orchestration | CrewAI + LangChain | | LLM | OpenAI gpt-4o (primary), Anthropic Claude (fallback/research) | | Voice transcription | OpenAI Whisper | | Image generation | DALL-E 3, Stability AI, Replicate | | Messaging | Twilio (WhatsApp) | | Database | Supabase (PostgreSQL) | | Task queue | Celery + Redis | | Reverse proxy | NGINX | | Containerization | Docker + Docker Compose | | Web search | Serper.dev + Brave Search | | OAuth | Google Calendar OAuth2, Notion OAuth2 |

Project Structure

jargsAI/
├── jargscormark/                     # Main backend application
│   ├── main.py                       # FastAPI entry point
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── .env.example
│   │
│   ├── config/
│   │   └── settings.py               # Pydantic BaseSettings — all config from .env
│   │
│   ├── backend/
│   │   ├── webhooks/
│   │   │   └── whatsapp.py           # Twilio webhook handler + signature validation
│   │   ├── api/
│   │   │   ├── routes.py             # Internal REST API (X-API-Key auth)
│   │   │   ├── google_auth_routes.py # Google Calendar OAuth2 callback
│   │   │   └── notion_auth_routes.py # Notion OAuth2 callback
│   │   ├── auth/
│   │   │   ├── google_oauth.py       # Google OAuth2 with PKCE
│   │   │   └── notion_oauth.py       # Notion per-user OAuth2
│   │   ├── database/
│   │   │   ├── supabase_client.py    # Supabase SDK wrapper
│   │   │   ├── models.py             # Pydantic DB models
│   │   │   └── migrations/schema.sql # 13-table schema
│   │   ├── queue/
│   │   │   ├── worker.py             # Celery app + 4 queue routing
│   │   │   └── jobs.py               # Background tasks (dispatch_to_crew, send_reminder…)
│   │   └── services/
│   │       ├── openclaw_client.py    # HTTP adapter for OpenClaw skills
│   │       ├── notion_client.py      # Notion API adapter
│   │       └── policy_engine.py      # Deterministic autonomy rules (LLM-proof)
│   │
│   ├── message_layer/
│   │   ├── normalizer.py             # Message normalization + session management
│   │   ├── voice_transcription.py    # OpenAI Whisper STT
│   │   └── whatsapp_delivery.py      # Twilio send + approval prompts
│   │
│   ├── agents/                       # CrewAI agent definitions
│   │   ├── executive_router.py       # Intent classification + routing
│   │   ├── secretary_agent.py        # Reminders, follow-ups, scheduling
│   │   ├── research_agent.py         # Live web research
│   │   ├── brand_strategy_agent.py   # Brand analysis
│   │   ├── content_writer_agent.py   # Social copy generation
│   │   ├── creative_director_agent.py# Visual design briefs
│   │   └── approval_agent.py         # L3 action approvals
│   │
│   ├── crews/                        # CrewAI orchestration flows
│   │   ├── task_automation_crew.py   # Entry crew: router -> policy -> executor
│   │   ├── content_creation_crew.py  # Strategy -> Write -> Design
│   │   └── research_crew.py          # Research agent flow
│   │
│   └── policy/
│       └── approval_policy.py        # Hard-coded autonomy level rules
│
├── openclaw_skills/                  # 16 skill modules (mounted as Docker volume)
│   ├── reminder_manager/
│   ├── followup_manager/
│   ├── google_calendar/
│   ├── research_analyst/
│   ├── caption_writer/
│   ├── design_brief_generator/
│   ├── content_calendar_planner/
│   ├── brand_memory_reader/
│   ├── notion_task_manager/
│   ├── pdf_generator/
│   ├── supabase_uploader/
│   ├── whatsapp_delivery_formatter/
│   ├── voice_command_handler/
│   ├── approval_policy_enforcer/
│   └── intent_router/
│
├── skillrunner/                      # Lightweight FastAPI skill runner service
│   ├── Dockerfile
│   └── main.py                       # Skill HTTP API (:8080 internal)
│
├── nginx/
│   └── nginx.conf                    # TLS, rate limiting, security headers
│
├── docker-compose.yml                # 6-service stack
├── deploy.sh                         # SCP-based VPS deployment script
└── ARCHITECTURE.md                   # Full architecture deep-dive

Message Flow (Overview)

WhatsApp User
     |
     v
[Twilio Webhook] --> [Message Normalizer] --> [Voice Transcription? (Whisper)]
     |
     v
[Celery Queue: crew]
     |
     v
[Executive Router — CrewAI]
  Intent classification + entity extraction
     |
     +---> [Policy Engine] (deterministic — LLM cannot override)
     |         Decides: AUTO (L1) | REVIEW (L2) | CONFIRM (L3)
     |
     +---> [Execution Handler]
     |       simple_tool  --> OpenClaw skill
     |       single_agent --> CrewAI agent --> OpenClaw skill
     |       multi_agent  --> Content/Research Crew --> OpenClaw skills
     |
     +---> [Approval Gate]
               L1 -> execute immediately
               L2 -> send draft for review
               L3 -> send YES/NO prompt, wait for reply
     |
     v
[WhatsApp Response via Twilio]

Autonomy Levels

| Level | Behavior | Examples | |---|---|---| | 1 — AUTO | Execute immediately | Reminders, research, captions, calendar read, general chat | | 2 — REVIEW | Generate draft, send for user review | Flyers, carousels, banners, content calendars | | 3 — CONFIRM | Require explicit YES before executing | Send message, send email, post publicly, delete event |

The policy engine enforces these levels deterministically — the LLM router cannot override them.

Features

| Feature | Autonomy | Integrations Used | |---|---|---| | Set reminders | L1 | Supabase, Celery | | Schedule follow-ups | L1 | Supabase, Celery | | Google Calendar (read/create) | L1 | Google Calendar API | | Google Calendar (update/delete) | L3 | Google Calendar API | | Web research + PDF report | L1 | Brave, Serper, Claude, ReportLab | | Social media captions | L1 | OpenAI gpt-4o | | Content calendar (monthly plan) | L2 | OpenAI gpt-4o | | Flyers / carousels / design briefs | L2 | DALL-E 3 / Stability AI | | Notion task management | L1 | Notion API (per-user OAuth) | | Voice command handling | L1 | OpenAI Whisper | | Send message / email | L3 | Twilio / (SendGrid planned) | | Post content to social media | L3 | (Instagram Graph API — planned) |

Docker Services

nginx       — public reverse proxy, TLS termination, rate limiting
backend     — FastAPI + CrewAI (port 8000, internal)
worker      — Celery worker (queues: crew, reminders, design, research)
scheduler   — Celery Beat (cron-like task scheduling)
openclaw    — OpenClaw skill runner (port 8080, internal only)
redis       — Celery broker + result backend (port 6379, internal only)

Quick Start (Local Dev)

# 1. Clone and configure
cd jargscormark
cp .env.example .env
# Fill in your keys (see Environment Variables section in ARCHITECTURE.md)

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the FastAPI server
python main.py

# 4. Run Celery worker (separate terminal)
celery -A backend.queue.worker worker --loglevel=info -Q crew,reminders,design,research

# 5. Run Celery Beat scheduler (separate terminal)
celery -A backend.queue.worker beat --loglevel=info

Production Deployment (Docker)

# Full stack via Docker Compose
docker-compose up -d

# Fast deploy (Python-only changes, ~10s)
./deploy.sh fast

# Full rebuild (requirements.txt changed, ~1 min)
./deploy.sh full

See PRODUCTION_DEPLOY.md for VPS setup, TLS/certbot configuration, and NGINX setup.

Key Environment Variables

# Required
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_WHATSAPP_NUMBER=

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
SERPER_API_KEY=

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

INTERNAL_API_KEY=           # 32+ chars, for /api/v1/* routes
OPENCLAW_GATEWAY_TOKEN=     # 32+ chars, backend <-> openclaw auth
APP_SECRET_KEY=             # 32+ chars, FastAPI session signing

# Google Calendar OAuth2
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=

# Notion OAuth2
NOTION_CLIENT_ID=
NOTION_CLIENT_SECRET=
NOTION_REDIRECT_URI=

# Optional
BRAVE_API_KEY=              # Backup search provider
STABILITY_AI_API_KEY=       # Fallback image generation
REPLICATE_API_TOKEN=        # Fallback image generation
SENTRY_DSN=                 # Error tracking

API Endpoints

Public

| Method | Path | Description | |---|---|---| | POST | /webhooks/whatsapp | Twilio message ingest (signature-validated) | | GET | /api/v1/health | Health check | | GET | /auth/google/callback | Google OAuth2 redirect | | GET | /auth/notion/callback | Notion OAuth2 redirect |

Internal (requires X-API-Key header)

| Method | Path | Description | |---|---|---| | POST | /api/v1/brand-profile | Create/update brand profile | | GET | /api/v1/reminders/{whatsapp} | List user's reminders | | POST | /api/v1/approve | Submit YES/NO approval response |