LWLT-AIBOT/.project-docs/20-architecture/data-flow.md

Data Flow

Primary Flows

Flow	Source	Destination	Notes
Business directive	Employee manual workbench or AgentBus	Route orchestrator	Manual input uses a signed-in team lead/user; AgentBus input uses the channel's bound employee account and its route allowlist. Administrators cannot enter this flow.
AgentBus execution ownership	Enabled channel	Employee account → immutable task assignee → executable feed	One account owns at most one channel; unbound channels and unassigned historical tasks stay non-executable.
Manual account authorization	Signed-in employee plus resolved business route	Intake and task-transition gates	Team leads/users require explicit grants; administrators manage grants but hold none, and denied or unresolved routes fail closed.
Parsing	19-route orchestrator	AI Skill or deterministic Program parser	AI/Shadow/Auto/Program mode is frozen per task; the external Agent exposes 18 routes and three routes are Program-only
Operation	Parser	Control-plane task and confirmation	Must validate against the same final contract
ERP execution	Confirmed task	Chrome extension and logged-in ERP page	Requires unique object, page identity, ownership, and write preflight
Completion evidence	ERP response/requery	Control-plane receipt and business reply	Evidence is action-specific; uncertain writes fail closed
Passenger workbook	Single .xls/.xlsx attachment	Deterministic encrypted canonical TSV	Exactly one complete ERP-semantic header is detected in rows 1–100 through finite aliases and arbitrary column order; exact leader-contact rules remain.
WeChat roster attachment	Strict transport envelope plus one structured payload.attachments[] entry	Existing awaiting_attachment task	Explicit conversation ID wins; otherwise strict Conversation: supplies the fallback. Placeholder text alone never creates a task.
Internal attachment download	Credential-free HTTPS URL	Bounded in-memory workbook bytes	Internal/private DNS answers are allowed; the selected address is pinned, every redirect is revalidated, and URL/host/IP/bytes are omitted from logs.
Operational diagnostics	Service, request, task, parser, AgentBus, attachment, database, and cleanup stages	Structured stdout/stderr and bounded Docker logs	Correlation identifiers, codes, outcomes, and durations only; no secrets or business payloads.
Platform operations oversight	Durably assigned manual/AgentBus task, encrypted instruction history, and readable outcome	Team-lead-only leadership projection	Immutable assignee is the employee dimension; unassigned historical AgentBus rows are excluded. Display-only summaries plus explicit filters drive an aggregate-first task/person/input/output/time/type/completion view, with bounded list reads and page-only detail hydration.
Leader task summary	Future stable manual/AgentBus task outcome for a durably assigned non-admin employee	Privacy projection → encrypted organization/revision outbox → fixed external Webhook → leader group	Independent from AgentBus task replies and ERP execution; strict success means accepted, not delivered, and rejected/uncertain attempts terminate without automatic retry.
Shared-child batch creation	Inclusive departure range plus exact product/customer/counts	Complete read-only parent enumeration → validated date/tid target list → sequential single-child adapter reuse	All targets are known before the first write; execution is deterministic and stops at the first blocked, failed, or uncertain result with remaining targets not started.
Browser worker selection	Immutable task assignee	One fresh account-bound browser connection	The heartbeat must prove the expected ERP identity from one unique login node by normalized exact equality; missing, duplicate, blank, substring-only, or mismatched identity is non-executable, with failover only after staleness.
Account-scoped ERP queue	Confirmed task assignee	Assigned account's browser worker	Organization-plus-account advisory locking preserves FIFO and at most one active execution for that account; another account's active, queued, stale, or uncertain work is outside this queue.
Executable event and result routing	Immutable task assignee	Matching authenticated employee page and plugin	Task APIs, SSE history/live events, claims, plugin results, and browser cleanup commands require a team-lead/user session matching the assignee; administrators are rejected before task handling.
Task removal	Owning employee	Archive/restore or permanent force delete	Archive/restore remains reversible and state-gated. Explicit owner force delete has no lifecycle-state gate, removes task-owned platform records atomically, retains a minimal deletion audit marker, and performs post-commit artifact/plugin cleanup best effort. Administrators cannot invoke either path.
Confirmation export	ERP source file	Archived source plus mobile delivery artifact	Visitor XLS becomes real XLSX; other types prefer PDF
Release	Editable source	dist/release-manifest.json and versioned artifacts	Manifest owns current hashes and filenames

State Ownership

• PostgreSQL owns durable control-plane account, management/task-plane role constraints, exact expected ERP identity, employee task-route grant, AgentBus channel owner, immutable task assignee, account-scoped queue/lease state, browser worker, session, confirmation, audit, archive, outcome state, and revisioned leader-summary Webhook state/deliveries. Migration 021 removes and rejects administrator task principals, migration 022 admits the new route without granting it, and migration 023 retires unsent legacy AgentBus summaries. Webhook payloads remain encrypted at rest while the URL/token remain runtime-only. A force-deleted task no longer exists in task state; only its minimal non-content deletion audit marker remains, while an externally accepted summary cannot be retracted.
• Production attachment bytes use the configured OSS provider; normalized sensitive fields remain encrypted.
• Chrome extension local state is bounded execution/reconciliation support, not canonical business history.
• .project-docs/30-worklog/tasks/ owns task-local project memory; canonical project state is an integrated projection.

External Interfaces

• Employee task workbench and separate administrator management pages at the control-plane service.
• AgentBus WebSocket channels and attachment delivery for normal employee task traffic.
• Fixed external Webhook for organization-level leader-summary delivery.
• Logged-in ERP browser pages under the Chrome extension host permissions.
• PostgreSQL, OSS, deployment gateway, and authenticated artifact download.

Last Updated

2026-09-09