Multi-platform messaging transport (Signal, WhatsApp via Neonize runtime, Instagram gateway/runtime, XMPP bridge).
AI-assisted drafting, summaries, pattern extraction, and mitigation planning.
Queueing and approval workflows for controlled outbound messaging.

This document covers architecture, setup, runtime behavior, and development workflow.

Architecture

High-level flow

Transport clients receive messages (Signal/WhatsApp/Instagram/XMPP).
UR (manage.py ur) normalizes events and routes them through unified handlers.
Message history is persisted in Django models (Message, ChatSession, identifiers).
UI pages (workspace + manual compose) read/write through Django views.
AI operations run through configured AI provider rows and store results in workspace models.

Core components

core/modules/router.py:
- Unified Router entrypoint.
- Starts transport clients.
- Cross-protocol typing/read events.
core/clients/:
- signal.py + signalapi.py: Signal transport integration.
- whatsapp.py: Neonize-backed WhatsApp runtime client.
- instagram.py: Instagram runtime/gateway integration.
- xmpp.py: XMPP bridge client.
- transport.py: Unified send/typing/QR API used by views/models.
core/messaging/:
- AI execution wrapper.
- Message history persistence and enrichment helpers.
core/views/:
- workspace.py: AI workspace, insights, mitigation plans/artifacts.
- compose.py: Manual chat mode, AI drafts/summary/engage shortcuts.
- signal.py, whatsapp.py, instagram.py: Service setup/account pages.

Data model highlights

Person + PersonIdentifier:
- Identity layer across services (signal, whatsapp, instagram, xmpp).
ChatSession + Message:
- Conversation storage.
- Delivery/read metadata fields on Message.
WorkspaceConversation:
- AI workspace context per person/thread.
- Stability + commitment scores and confidence.
WorkspaceMetricSnapshot:
- Historical metric snapshots for trend charts.
Pattern mitigation models:
- PatternMitigationPlan, Rule, Game, Correction, exports, and auto settings.

Runtime services

docker-compose.yml defines these primary services:

app: Django web process.
ur: Unified Router runtime (transport clients).
scheduling: Scheduled jobs.
migration: Startup migrations.
collectstatic: Static asset collection.
redis: Cache/runtime signaling.
signal-cli-rest-api: Signal backend.

Installation

Prerequisites

Podman + Podman Compose (preferred in this repo), or Docker Compose.
Linux environment with bind-mount access for configured paths.

1) Clone and configure

git clone <your-repo-url> GIA
cd GIA
cp stack.env.example stack.env

Edit stack.env with at least:

SECRET_KEY
ALLOWED_HOSTS
CSRF_TRUSTED_ORIGINS
SIGNAL_NUMBER (if Signal enabled)
WHATSAPP_ENABLED=true|false
INSTAGRAM_ENABLED=true|false
XMPP values if XMPP bridge is enabled

2) Build and start

make build
make run

3) Run migrations and create admin user

make migrate
make auth

4) Follow logs

make log

Local developer commands

make makemigrations
make migrate
make test

Run ad-hoc manage commands:

docker-compose --env-file=stack.env run --rm app \
  sh -c ". /venv/bin/activate && python manage.py <command>"

Service setup pages

Signal: /services/signal/
WhatsApp: /services/whatsapp/
Instagram: /services/instagram/

WhatsApp pairing (Neonize)

WhatsApp account linking expects a real Neonize runtime QR:

Start stack with WHATSAPP_ENABLED=true.
Ensure ur is running and WhatsApp runtime initialized.
Open Services -> WhatsApp -> Add Account.
Scan QR from WhatsApp Linked Devices.

If runtime QR is not available yet, UI returns a clear warning instead of a synthetic QR.

Manual compose mode

Route: /compose/page/?service=<service>&identifier=<id>[&person=<uuid>]
Features:
- Chat thread view.
- Send with two-step failsafe (Arm Send + Confirm Intent).
- AI overlay tools:
  - Draft suggestions.
  - Conversation summary.
  - Quick engage send (shared framing, with its own two-step failsafe).
- Click-outside dismiss behavior for AI overlays.

Live updates and traffic minimization

WebSocket endpoint: /ws/compose/thread/ (ASGI path).
Compose clients open one persistent WS per panel and receive incremental updates.
HTTP polling remains as a fallback at a slower interval when WS is unavailable.

This reduces repeated client GET requests compared with short polling loops.

AI workspace

Route: /ai/workspace/

Key capabilities:

Summary, draft, pattern extraction.
Mitigation planning and artifacts (rules/games/corrections).
Insight metrics:
- Detail pages per metric.
- All-graphs page using Chart.js.
- Scoring help page describing formulas and interpretation.

Configuration notes

app/local_settings.py is imported by app/settings.py.
Redis cache is expected at /var/run/gia-redis.sock unless overridden.
Service runtime URLs are read by core/clients/transport.py:
- SIGNAL_HTTP_URL
- WHATSAPP_HTTP_URL
- INSTAGRAM_HTTP_URL

ASGI / WebSocket note

app/asgi.py now multiplexes:

HTTP to Django ASGI app.
WebSocket path /ws/compose/thread/ to compose realtime handler.

Use an ASGI-capable server in environments where WebSockets are required.

Troubleshooting

“Send failed. Check service account state.”

Verify service account is linked and runtime is connected.
Check ur and service logs (make log).

WhatsApp QR not available

Confirm WHATSAPP_ENABLED=true.
Confirm Neonize initializes in ur logs.
Retry Add Account after runtime is ready.

No compose realtime updates

Verify ASGI deployment path and websocket upgrade support.
Fallback polling should still update messages on interval.

Security and operational safety

Outbound actions in manual compose/engage are guarded by two-step failsafe toggles.
Queue workflow exists for additional human approval in managed flows.
Deploy only with lawful consent and compliant data handling for your jurisdiction.