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.