Implement reactions and image sync
This commit is contained in:
286
README.md
286
README.md
@@ -1,198 +1,170 @@
|
||||
# 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.
|
||||
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.
|
||||
|
||||
This document covers architecture, setup, runtime behavior, and development workflow.
|
||||
> Start with `INSTALL.md` first. This README focuses on capabilities and operation modes.
|
||||
|
||||
## Architecture
|
||||
## What GIA Does
|
||||
|
||||
### 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.
|
||||
- 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.
|
||||
|
||||
### 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.
|
||||
## Operation Modes
|
||||
|
||||
### 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.
|
||||
## 1) Service Management Mode
|
||||
|
||||
## Runtime services
|
||||
Entry points:
|
||||
|
||||
`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.
|
||||
- `/services/signal/`
|
||||
- `/services/whatsapp/`
|
||||
- `/services/instagram/`
|
||||
|
||||
## Installation
|
||||
Capabilities:
|
||||
|
||||
### Prerequisites
|
||||
- Podman + Podman Compose (preferred in this repo), or Docker Compose.
|
||||
- Linux environment with bind-mount access for configured paths.
|
||||
- Account linking/unlinking.
|
||||
- Contact and chat discovery views.
|
||||
- Message list inspection (service-native views).
|
||||
- Runtime state visibility (connection/linking behavior through logs + UI state).
|
||||
|
||||
### 1) Clone and configure
|
||||
```bash
|
||||
git clone <your-repo-url> GIA
|
||||
cd GIA
|
||||
cp stack.env.example stack.env
|
||||
```
|
||||
## 2) Manual Compose Mode
|
||||
|
||||
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
|
||||
Entry points:
|
||||
|
||||
### 2) Build and start
|
||||
```bash
|
||||
make build
|
||||
make run
|
||||
```
|
||||
- `/compose/page/`
|
||||
- `/compose/widget/`
|
||||
- `/compose/workspace/`
|
||||
|
||||
### 3) Run migrations and create admin user
|
||||
```bash
|
||||
make migrate
|
||||
make auth
|
||||
```
|
||||
Capabilities:
|
||||
|
||||
### 4) Follow logs
|
||||
```bash
|
||||
make log
|
||||
```
|
||||
- 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.
|
||||
|
||||
## Local developer commands
|
||||
Compose operational behaviors:
|
||||
|
||||
```bash
|
||||
make makemigrations
|
||||
make migrate
|
||||
make test
|
||||
```
|
||||
- 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.
|
||||
|
||||
Run ad-hoc manage commands:
|
||||
```bash
|
||||
docker-compose --env-file=stack.env run --rm app \
|
||||
sh -c ". /venv/bin/activate && python manage.py <command>"
|
||||
```
|
||||
## 3) AI Workspace Mode
|
||||
|
||||
## Service setup pages
|
||||
Entry point:
|
||||
|
||||
- Signal: `/services/signal/`
|
||||
- WhatsApp: `/services/whatsapp/`
|
||||
- Instagram: `/services/instagram/`
|
||||
- `/ai/workspace/`
|
||||
|
||||
### 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.
|
||||
Capabilities:
|
||||
|
||||
If runtime QR is not available yet, UI returns a clear warning instead of a synthetic QR.
|
||||
- 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).
|
||||
|
||||
## Manual compose mode
|
||||
## 4) Queue / Approval 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.
|
||||
Entry points:
|
||||
|
||||
### 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.
|
||||
- `/queue/<type>/`
|
||||
- API:
|
||||
- `/api/v1/queue/message/accept/<message_id>/`
|
||||
- `/api/v1/queue/message/reject/<message_id>/`
|
||||
|
||||
This reduces repeated client GET requests compared with short polling loops.
|
||||
Capabilities:
|
||||
|
||||
## AI workspace
|
||||
- Hold suggested outbound actions.
|
||||
- Human acceptance/rejection gates.
|
||||
- Queue-first messaging flows for controlled operations.
|
||||
|
||||
Route: `/ai/workspace/`
|
||||
## 5) OSINT Mode
|
||||
|
||||
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.
|
||||
Entry points:
|
||||
|
||||
## Configuration notes
|
||||
- `/search/<type>/`
|
||||
- `/osint/workspace/`
|
||||
|
||||
- `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`
|
||||
Capabilities:
|
||||
|
||||
## ASGI / WebSocket note
|
||||
- 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.
|
||||
|
||||
`app/asgi.py` now multiplexes:
|
||||
- HTTP to Django ASGI app.
|
||||
- WebSocket path `/ws/compose/thread/` to compose realtime handler.
|
||||
## 6) Cross-Protocol Bridge Mode
|
||||
|
||||
Use an ASGI-capable server in environments where WebSockets are required.
|
||||
Core behavior:
|
||||
|
||||
## Troubleshooting
|
||||
- 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.
|
||||
|
||||
### “Send failed. Check service account state.”
|
||||
- Verify service account is linked and runtime is connected.
|
||||
- Check `ur` and service logs (`make log`).
|
||||
Key design points:
|
||||
|
||||
### WhatsApp QR not available
|
||||
- Confirm `WHATSAPP_ENABLED=true`.
|
||||
- Confirm Neonize initializes in `ur` logs.
|
||||
- Retry Add Account after runtime is ready.
|
||||
- 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.
|
||||
|
||||
### No compose realtime updates
|
||||
- Verify ASGI deployment path and websocket upgrade support.
|
||||
- Fallback polling should still update messages on interval.
|
||||
## Runtime Architecture
|
||||
|
||||
## Security and operational safety
|
||||
Core components:
|
||||
|
||||
- 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.
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user