GIA/README.md

# GIA

GIA is a Django-based communications workspace that combines:
- 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
1. Transport clients receive messages (Signal/WhatsApp/Instagram/XMPP).
2. UR (`manage.py ur`) normalizes events and routes them through unified handlers.
3. Message history is persisted in Django models (`Message`, `ChatSession`, identifiers).
4. UI pages (workspace + manual compose) read/write through Django views.
5. 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
```bash
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
```bash
make build
make run
```

### 3) Run migrations and create admin user
```bash
make migrate
make auth
```

### 4) Follow logs
```bash
make log
```

## Local developer commands

```bash
make makemigrations
make migrate
make test
```

Run ad-hoc manage commands:
```bash
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:
1. Start stack with `WHATSAPP_ENABLED=true`.
2. Ensure `ur` is running and WhatsApp runtime initialized.
3. Open `Services -> WhatsApp -> Add Account`.
4. 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.