171 lines
5.5 KiB
Markdown
171 lines
5.5 KiB
Markdown
# 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.
|