WalletOps Companion is a monorepo: Go API + Postgres worker-in-process, Flutter client.
[Flutter app]
| JSON + JWT
v
[Go API] ---- auth / rules / events / ai.summarize
|---- POST /webhooks/events (HMAC)
v
[Postgres]
^
[Worker goroutine]
sequenceDiagram
participant Partner as Partner/script
participant API as Go API
participant DB as Postgres
participant Worker as In-process worker
participant Mobile as Flutter app
participant AI as AI provider (mock/openai)
Partner->>API: POST /v1/webhooks/events + HMAC
API->>API: Verify signature
API->>DB: Insert event status=pending (idempotent)
API-->>Partner: 202/200 event
Worker->>DB: Claim pending/failed/stale processing (SKIP LOCKED + lease)
Worker->>DB: Match alert rules, mark processed/failed
Worker-->>DB: Update status + matched_rule_id
Mobile->>API: GET /v1/events (JWT)
API->>DB: List owned events
API-->>Mobile: items[]
Mobile->>API: POST /v1/ai/summarize {event_ids}
API->>DB: Load owned events + rule names
API->>AI: Allowlisted prompt fields only
AI-->>API: Schema JSON summary
API->>DB: Insert ai_summaries
API-->>Mobile: title, bullets, risk_level, follow_ups
- Select one eligible row:
pending, retriablefailed, orprocessingwhoseclaimed_atlease expired. FOR UPDATE SKIP LOCKEDso two API processes do not take the same row.- Set
status=processingand refreshclaimed_at. - Match rules / validate payload; mark
processedorfailed(clearsclaimed_at).
Default lease: 45s (events.ClaimLease). Health exposes queue counts via GET /v1/health.
| Path | Role |
|---|---|
internal/auth |
Register/login/refresh, JWT middleware |
internal/rules |
Alert rule CRUD + matching lookup |
internal/events |
Persist/list/claim events, queue stats |
internal/webhook |
HMAC ingest |
internal/worker |
Poll/claim/process loop |
internal/ai |
Mock/OpenAI summarize + audit row |
Feature-first layout (data / domain / presentation):
| Path | Role |
|---|---|
features/*/domain |
Repository contracts |
features/*/data |
Dio APIs + *RepositoryImpl (guardApi maps errors) |
features/*/presentation |
Cubits + pages (no Dio / no getIt in widgets) |
features/shell |
Authenticated chrome + indexed tab shell |
features/ops |
OpsHealthCubit polls /v1/health with skipAuth |
core/error |
AppException + Dio → domain mapping |
core/network |
Shared Dio client + auth interceptor |
core/di |
GetIt composition root |
State scope: app (AuthCubit, OpsHealthCubit) → shell (EventsCubit, RulesCubit, survive tabs) → route (detail / explain).