# GIA

GIA is a multi-transport communication workspace that unifies Signal, WhatsApp, Instagram, and XMPP into one operator interface with AI-assisted analysis, drafting, and mitigation workflows.

> Start with `INSTALL.md` first. This README focuses on capabilities and operation modes.

## What GIA Does

- Unifies chats from multiple protocols in one interface.
- Keeps conversation history in a shared model (`Person`, `PersonIdentifier`, `ChatSession`, `Message`).
- Supports manual, queue-driven, and AI-assisted outbound messaging.
- Bridges messages across transports (including XMPP) with attachment handling.
- Tracks delivery/read metadata and typing state events.
- Provides AI workspace analytics, mitigation plans, and insight visualizations.

## Operation Modes

## 1) Service Management Mode

Entry points:

- `/services/signal/`
- `/services/whatsapp/`
- `/services/instagram/`

Capabilities:

- Account linking/unlinking.
- Contact and chat discovery views.
- Message list inspection (service-native views).
- Runtime state visibility (connection/linking behavior through logs + UI state).

## 2) Manual Compose Mode

Entry points:

- `/compose/page/`
- `/compose/widget/`
- `/compose/workspace/`

Capabilities:

- Per-person/per-service chat thread view.
- Outbound send with runtime handoff for relevant services.
- Thread refresh/history sync path.
- Real-time updates via compose websocket path (with fallback behavior).
- Inline metadata for delivery/read timing.
- Latency and block-gap indicators for conversational cadence.

Compose operational behaviors:

- Manual sends are persisted to history and propagated to runtime transports.
- Runtime command-result polling handles queued sends where needed.
- Attachments are normalized through shared transport media prep logic.
- Blob URLs are fallback paths; source/shared media URLs are preferred when available.

## 3) AI Workspace Mode

Entry point:

- `/ai/workspace/`

Capabilities:

- Person-centric workspace widgets and timelines.
- Draft generation, summary generation, quick insights.
- Insight detail pages and graph visualizations.
- Mitigation planning (rules, games, corrections, fundamentals, automation settings).
- Engage flows (preview + send).

## 4) Queue / Approval Mode

Entry points:

- `/queue/<type>/`
- API:
  - `/api/v1/queue/message/accept/<message_id>/`
  - `/api/v1/queue/message/reject/<message_id>/`

Capabilities:

- Hold suggested outbound actions.
- Human acceptance/rejection gates.
- Queue-first messaging flows for controlled operations.

## 5) OSINT Mode

Entry points:

- `/search/<type>/`
- `/osint/workspace/`

Capabilities:

- Search pages and widgets for scoped entity views.
- Workspace tab widgets and cross-context lookup UX.
- Foundation for auto-search workflows and graph/widget integration.

## 6) Cross-Protocol Bridge Mode

Core behavior:

- Inbound and outbound events are routed through UR runtime.
- XMPP bridge supports text, attachments, typing, and chat-state paths.
- Signal and WhatsApp media relay paths are normalized via shared transport/media logic.

Key design points:

- Prefer shared media preparation over per-service duplicated logic.
- Preserve attachment semantics (image/video/audio/document) by MIME and filename inference.
- Avoid leaking internal `/compose/media/blob/...` links as transport relay text for attachment-only events.

## Runtime Architecture

Core components:

- `core/modules/router.py`: Unified Router runtime orchestration.
- `core/clients/transport.py`: Shared send/typing/attachment prep/runtime-command layer.
- `core/clients/signal.py`, `core/clients/signalapi.py`: Signal event + REST transport handling.
- `core/clients/whatsapp.py`: Neonize-backed runtime transport.
- `core/clients/xmpp.py`: XMPP component bridge and media upload relay.
- `core/views/compose.py`: Manual compose UX, polling/ws, send pipeline, media blob endpoint.
- `core/views/workspace.py`: AI workspace operations and insight surfaces.
- `core/views/osint.py`: Search/workspace OSINT interactions.

Services in compose stack:

- `app` (Django)
- `asgi` (websocket-capable app path)
- `ur` (runtime router)
- `scheduling`
- `redis`
- `signal-cli-rest-api`
- one-shot startup services (`migration`, `collectstatic`)

## Interface Setup (Inside the App)

After environment setup from `INSTALL.md`:

1. Sign in as an admin user.
2. Open service pages and link required accounts.
3. Create/verify `Person` entries and `PersonIdentifier` mappings.
4. Open manual compose and test per-service send/receive.
5. Open AI workspace for analysis/mitigation workflows.
6. Verify queue workflows if approval mode is used.

Recommended functional smoke test:

- Signal -> web compose history
- WhatsApp -> web compose history
- XMPP -> service relay and back
- attachment send in both directions where bridge is enabled

## Important Operational Notes

- After runtime code changes, restart runtime services before validation.
- Full environment recycle convention: `make stop && make run`.
- If single-service restart fails due to dependency state, use full recycle.

## Security & Reliability Notes

- Keep upload endpoints on modern TLS (`TLSv1.2` + `TLSv1.3`) with valid chain.
- Keep logs high-signal in production; use debug-gated diagnostics temporarily.
- Preserve symmetry across transports where protocol capabilities permit.

## Documentation Map

- `INSTALL.md`: installation, env, startup, restart, troubleshooting.
- `LLM_CODING_STANDARDS.md`: coding-agent standards and repository practices.
- This `README.md`: capability map, operation modes, architecture, interface workflow.