LWLT-AIBOT/.project-docs/20-architecture/system-overview.md

System Overview

Current Architecture

Authenticated manual or AgentBus input is routed through task-scoped AI/Shadow/Auto/Program orchestration into one validated operation contract. The control plane owns account, task, session, task-type authorization, confirmation, audit, and archive state, and the Chrome extension resolves the unique ERP object, enforces page and write gates, performs native actions, and returns action-specific evidence.

Main Components

Component	Responsibility	Notes
agent设计规范/	Agent Prompt, five parsing Skills, business templates, business registry, and stable fixtures	Editable source for business semantics; not runtime evidence
schemas/ and mappings/	Parse-state, execution-state, ERP form, field, and lifecycle contracts	Current contracts only
control-plane/	Task/session persistence, parser orchestration, confirmation, audit, AgentBus, attachments, receipts, and structured diagnostics	TypeScript source; build output goes to .build/
LianSyn-platform/	Operator workbench and external parser adapter	Source and UI, not local task output
chrome-extension/ltjt-order-assistant/	Logged-in ERP resolution, preflight, native execution, response handling, and requery	Any code change requires synchronized versioned release updates
dist/	Versioned current deliverables and machine-readable release manifest	Not a compilation directory
.project-docs/	Task-isolated project memory and integrated canonical context	No runtime dependency
archive/	Date-scoped immutable history and evidence	Never defines current behavior

Important Boundaries

• AI/Program parsing and ERP resolution/execution share the final operation contract but do not share authority.
• Platform envelope fields such as task ID, account identity, authorization revision, session, parser decision, confirmation, transport, and audit never enter the business operation.
• The product is one fixed internal organization scope with three roles. Administrators manage accounts and all 18 manual routes; team leads and users are owner-scoped for normal tasks and require explicit per-route grants. Team leads additionally receive a dedicated read-only, manual-task-only platform-operations dashboard.
• Account passwords are accepted when non-empty without an application-level length rule. First-login forced password changes are disabled; voluntary changes and administrator resets still revoke the relevant sessions, while the historical must_change_password column remains compatibility-only storage.
• The leadership dashboard is an aggregate-first projection across task, person, original input, final output, time, task type, and completion state. Its drill-through stays business-facing; technical payloads, internal identifiers, machine-shaped historical input, and technical failure text remain in separate authorized audit/engineering surfaces.
• Authorization is enforced in server and service paths, not by navigation visibility. A denied or unresolved non-admin business route stops before parsing, plugin dispatch, and ERP execution; creator authorization is rechecked at confirmation and browser claim.
• Creator and manual input-turn attribution remain durable while business input stays encrypted at rest. Routine removal is reversible archive/restore; physical purge is not an operator capability.
• Unknown, ambiguous, unverified, or post-write-uncertain states fail closed; automatic retries must not create duplicate writes.
• PostgreSQL is the sole required durable database/state middleware, and the production artifact provider is OSS. Redis, message queues, MongoDB, and search services are not runtime dependencies.
• Migrations must complete before the application starts. The current ACK topology starts with one application replica because AgentBus listeners and SSE emission are process-local; horizontal scale requires explicit coordination first.
• Operational diagnostics are privacy-safe structured JSON on stdout/stderr. Docker owns bounded rotation; repository files and a second mutable log database are not log sinks.
• In the trusted internal deployment, AgentBus roster attachment downloads may resolve to private/reserved addresses. Credential-free HTTPS, DNS resolution/pinning, redirect revalidation, size, timeout, and digest checks remain mandatory, and trusted channels/bridges own the network-input boundary.
• Canonical project memory is updated only under Integration Gate; feature tasks write only their task-scoped records.

Related Decisions

• DOC-001
• ARCH-001
• ROUTE-001
• RELEASE-001
• SAFETY-001
• NETWORK-001
• AUTH-001

Last Updated

2026-09-02