How 6stephen-git/after-sales-e-commerce-assistant works
1. Overall shape
- This repository is a two-tier application: a Vue frontend and a Python backend.
- The backend is not a simple CRUD API; it runs a multi-agent analysis pipeline for dispute/case evaluation, with caching, rule matching, and optional background review jobs.
2. Frontend boundary
- frontend/src/views/DisputeView.vue and SettingsView.vue are the main screens.
- The UI is organized around two presentation modes: a chat panel (components/chat) and a strategy panel (components/strategy with fact, strategy, script, and emotion cards).
- src/api/index.js and src/composables/useDispute.js are the main client-side integration points to the backend.
3. API layer
- The backend exposes route modules in backend/routers/, especially analyze.py, plus domain-specific routers for buyers.py and merchants.py.
- backend/main.py is the application entry point, and backend/controllers/assisted_controller.py likely orchestrates the primary analysis request flow.
4. Core analysis pipeline
- The backend is built around five agents under backend/agents/:
- Agent 1: fact extraction and rule planning
- Agent 2: strategy generation
- Agent 3: script generation
- Agent 4: emotion monitoring
- Agent 5: review/revision
- This suggests a staged pipeline where output from earlier agents feeds later ones rather than a single monolithic model call.
5. Tooling and model integration
- backend/tools/llm_client.py is the central abstraction for LLM access.
- platform_api.py and the agent-specific tool modules (agent1_tools.py through agent5_tools.py) provide domain and execution utilities.
- rule_matcher.py, rule_matcher_llm.py, and rule_lexicon.py indicate that rule identification is partly deterministic and partly LLM-assisted.
6. Rule knowledge layer
- The data/ directory contains curated rule assets: crawl targets, bundles, exports, a rule library index, and a rule-match lexicon.
- The scripts/ directory contains offline ingestion and preparation jobs for this knowledge base, including crawling, importing, and lexicon building.
- This makes the rule corpus a first-class input to the analysis pipeline, not just static reference data.
7. Caching and retrieval
- backend/cache/ separates short-lived and derived-state storage:
- redis_client.py for Redis connectivity
- fingerprint.py for request/material identity
- materials_store.py for stored inputs or evidence
- result_cache.py for cached analysis outputs
- The architecture implies repeated dispute analyses are deduplicated or accelerated using fingerprints and cached results.
8. Persistence layer
- backend/db/connection.py and models.py define the persistent store for backend state.
- The exact engine is not shown here, but the presence of connection/model separation suggests a relational database used for durable application data, distinct from Redis cache.
9. Asynchronous processing
- backend/tasks/celery_app.py and review_task.py show that some work is offloaded to a background worker.
- The likely purpose is deferred review, quality checks, or expensive agent execution that should not block the HTTP request cycle.
10. Domain and contract structure
- schemas.py, backend/defaults.py, and the test fixtures suggest a strongly shaped request/response contract.
- The repo also contains docs for API, database schema, frontend spec, and agent modules, which indicates the codebase is designed around explicit module boundaries and stable interfaces.
11. Validation and evaluation harness
- The tests/ tree is unusually rich: unit tests for agents and tools, API/e2e tests, dispute cache tests, and scenario/judge-based evaluation artifacts.
- tests/scenarios/, tests/prompts/, and tests/judge_* indicate the system is evaluated with scenario generation and automated judging, which is important if you are diagramming feedback loops or quality gates.
12. Main data flow to diagram
- A user interacts with the Vue frontend.
- The frontend calls the backend analyze API.
- The controller checks cache/material fingerprints, resolves or loads rule data, and runs the agent pipeline.
- Results may be persisted in the DB, cached in Redis, and optionally sent to a background review task.
- The final structured response is rendered back into the chat/strategy UI.
13. Operational support
- scripts/start.* suggests cross-platform local startup support.
- backend/requirements.txt, frontend/package.json, and Vite config show a standard Python service plus modern JS frontend setup.
- The repo is therefore best understood as a rule-informed, LLM-assisted dispute analysis platform with clear separations between UI, orchestration, knowledge ingestion, caching, persistence, and evaluation.
Main entry points: assisted_controller.py Assisted controller · index.js API client · llm_client.py LLM client · DisputeView.vue Dispute view
Components 22
Frontend
Vue UI, state hooks, and backend API integration
- Dispute view · Primary user workspace for dispute analysis and responses
frontend/src/views/DisputeView.vue - Settings view · Secondary configuration screen
frontend/src/views/SettingsView.vue - Chat panel · Conversation-oriented presentation layer
frontend/src/components/chat/ChatPanel.vue - Strategy panel · Structured fact/strategy/script/emotion presentation layer
frontend/src/components/strategy/StrategyPanel.vue - API client · Client-side backend integration entrypoint
frontend/src/api/index.js - Dispute hook · Frontend dispute state and request orchestration
frontend/src/composables/useDispute.js
Backend Core
HTTP entrypoint, controller, analysis pipeline, tools, cache, persistence, and async tasks
- App entry · Backend application bootstrap and wiring
backend/main.py - Analyze router · Primary analysis endpoint surface
backend/routers/analyze.py - Assisted controller · Coordinates request handling and pipeline execution
backend/controllers/assisted_controller.py - Fact planner · Extracts facts and plans rule matching
backend/agents/agent1/fact_extractor.py - Strategist · Generates dispute strategy from prior outputs
backend/agents/agent2/strategist.py - Script gen · Produces response scripts and messaging
backend/agents/agent3/script_generator.py - Emotion monitor · Tracks tone and emotional risk
backend/agents/agent4/emotion_monitor.py - Reviewer · Reviews and revises the pipeline result
backend/agents/agent5/reviewer.py - LLM client · Shared abstraction for model calls
backend/tools/llm_client.py - Rule matcher · Deterministic and LLM-assisted rule identification
backend/tools/rule_matcher.py - Result cache · Cached analysis outputs
backend/cache/result_cache.py - Fingerprinting · Derives request and material identity
backend/cache/fingerprint.py - DB models · Durable backend state and relational models
backend/db/models.py - Review task · Background review and revision processing
backend/tasks/review_task.py
Rule Knowledge
Curated rule assets and offline ingestion/build jobs
- Rule lexicon · Curated rule matching vocabulary
data/rule_match_lexicon.json - Lexicon build · Offline job that builds the rule lexicon
scripts/build_rule_match_lexicon.py
Connections 27
- Dispute view → API client: calls · Screen requests analysis and settings data
- Dispute view → Chat panel: renders · Chat mode presentation
- Dispute view → Strategy panel: renders · Strategy mode presentation
- Settings view → API client: uses · Settings read/write flows
- Dispute hook → API client: wraps · Stateful dispute requests
- API client → Analyze router: HTTP · Client invokes backend analysis endpoint
- App entry → Analyze router: mounts · Registers API routes
- Analyze router → Assisted controller: delegates · Routes hand off to orchestration layer
- Assisted controller → Fingerprinting: keys · Identifies repeated requests/materials
- Assisted controller → Result cache: checks · Returns cached results when available
- Assisted controller → Rule matcher: matches · Loads and matches applicable rules
- Assisted controller → Fact planner: starts · First stage fact extraction and planning
- Fact planner → Strategist: feeds · Facts and rule plan inform strategy
- Strategist → Script gen: feeds · Strategy informs script generation
- Script gen → Emotion monitor: feeds · Draft response is checked for emotional risk
- Emotion monitor → Reviewer: feeds · Emotional review informs final revision
- Fact planner → LLM client: uses · Agent model access
- Strategist → LLM client: uses · Agent model access
- Script gen → LLM client: uses · Agent model access
- Emotion monitor → LLM client: uses · Agent model access
- Reviewer → LLM client: uses · Agent model access
- Rule matcher → Rule lexicon: reads · Matches against curated terminology
- Rule lexicon → Lexicon build: built by · Offline ingestion and lexicon construction
- Assisted controller → DB models: persists · Stores durable application state
- Assisted controller → Review task: queues · Offloads expensive or deferred review work
- Review task → Reviewer: runs · Background review worker uses reviewer stage
- Assisted controller → API client: responds to · Structured result returns to the UI