# 6stephen-git/after-sales-e-commerce-assistant architecture

> Architecture diagram of the GitHub repository 6stephen-git/after-sales-e-commerce-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/6stephen-git/after-sales-e-commerce-assistant
- Repository: https://github.com/6stephen-git/after-sales-e-commerce-assistant

## Overview

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: [`backend/controllers/assisted_controller.py`](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/controllers/assisted_controller.py) (Assisted controller), [`frontend/src/api/index.js`](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/api/index.js) (API client), [`backend/tools/llm_client.py`](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tools/llm_client.py) (LLM client), [`frontend/src/views/DisputeView.vue`](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/views/DisputeView.vue) (Dispute view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_views["Dispute view<br/>Vue screen<br/>[DisputeView.vue]"]
  node_frontend_settings["Settings view<br/>Vue screen<br/>[SettingsView.vue]"]
  node_frontend_chat["Chat panel<br/>UI component<br/>[ChatPanel.vue]"]
  node_frontend_strategy["Strategy panel<br/>UI component<br/>[StrategyPanel.vue]"]
  node_frontend_api["API client<br/>frontend API<br/>[index.js]"]
  node_frontend_hook["Dispute hook<br/>state composable<br/>[useDispute.js]"]
end

subgraph group_backend_core["Backend Core"]
  node_backend_main["App entry<br/>Python service<br/>[main.py]"]
  node_backend_router["Analyze router<br/>HTTP router<br/>[analyze.py]"]
  node_backend_controller["Assisted controller<br/>orchestrator"]
  node_agent1["Fact planner<br/>agent stage 1<br/>[fact_extractor.py]"]
  node_agent2["Strategist<br/>agent stage 2<br/>[strategist.py]"]
  node_agent3["Script gen<br/>agent stage 3"]
  node_agent4["Emotion monitor<br/>agent stage 4<br/>[emotion_monitor.py]"]
  node_agent5["Reviewer<br/>agent stage 5<br/>[reviewer.py]"]
  node_llm_client["LLM client<br/>model adapter<br/>[llm_client.py]"]
  node_rule_matcher["Rule matcher<br/>rule engine<br/>[rule_matcher.py]"]
  node_result_cache[("Result cache<br/>[result_cache.py]")]
  node_fingerprint{{"Fingerprinting<br/>cache key<br/>[fingerprint.py]"}}
  node_db_models[("DB models<br/>persistence<br/>[models.py]")]
  node_review_task["Review task<br/>worker job<br/>[review_task.py]"]
end

subgraph group_knowledge["Rule Knowledge"]
  node_rule_lexicon["Rule lexicon<br/>knowledge base"]
  node_lexicon_build["Lexicon build<br/>ingestion script"]
end

node_frontend_views -->|"calls"| node_frontend_api
node_frontend_views -->|"renders"| node_frontend_chat
node_frontend_views -->|"renders"| node_frontend_strategy
node_frontend_settings -->|"uses"| node_frontend_api
node_frontend_hook -->|"wraps"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_router
node_backend_main -->|"mounts"| node_backend_router
node_backend_router -->|"delegates"| node_backend_controller
node_backend_controller -->|"keys"| node_fingerprint
node_backend_controller -->|"checks"| node_result_cache
node_backend_controller -->|"matches"| node_rule_matcher
node_backend_controller -->|"starts"| node_agent1
node_agent1 -->|"feeds"| node_agent2
node_agent2 -->|"feeds"| node_agent3
node_agent3 -->|"feeds"| node_agent4
node_agent4 -->|"feeds"| node_agent5
node_agent1 -->|"uses"| node_llm_client
node_agent2 -->|"uses"| node_llm_client
node_agent3 -->|"uses"| node_llm_client
node_agent4 -->|"uses"| node_llm_client
node_agent5 -->|"uses"| node_llm_client
node_rule_matcher -->|"reads"| node_rule_lexicon
node_rule_lexicon -.->|"built by"| node_lexicon_build
node_backend_controller -->|"persists"| node_db_models
node_backend_controller -->|"queues"| node_review_task
node_review_task -->|"runs"| node_agent5
node_backend_controller -.->|"responds to"| node_frontend_api

click node_frontend_views "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/views/DisputeView.vue"
click node_frontend_settings "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/views/SettingsView.vue"
click node_frontend_chat "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/components/chat/ChatPanel.vue"
click node_frontend_strategy "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/components/strategy/StrategyPanel.vue"
click node_frontend_api "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/api/index.js"
click node_frontend_hook "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/composables/useDispute.js"
click node_backend_main "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/main.py"
click node_backend_router "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/routers/analyze.py"
click node_backend_controller "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/controllers/assisted_controller.py"
click node_agent1 "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent1/fact_extractor.py"
click node_agent2 "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent2/strategist.py"
click node_agent3 "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent3/script_generator.py"
click node_agent4 "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent4/emotion_monitor.py"
click node_agent5 "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent5/reviewer.py"
click node_llm_client "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tools/llm_client.py"
click node_rule_matcher "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tools/rule_matcher.py"
click node_result_cache "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/cache/result_cache.py"
click node_fingerprint "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/cache/fingerprint.py"
click node_db_models "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/db/models.py"
click node_review_task "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tasks/review_task.py"
click node_rule_lexicon "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/data/rule_match_lexicon.json"
click node_lexicon_build "https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/scripts/build_rule_match_lexicon.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_views,node_frontend_settings,node_frontend_chat,node_frontend_strategy,node_frontend_api,node_frontend_hook toneBlue
class node_backend_main,node_backend_router,node_backend_controller,node_agent1,node_agent2,node_agent3,node_agent4,node_agent5,node_llm_client,node_rule_matcher,node_result_cache,node_fingerprint,node_db_models,node_review_task toneAmber
class node_rule_lexicon,node_lexicon_build toneMint
```

## Components

### Frontend

Vue UI, state hooks, and backend API integration

- [Dispute view](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/views/DisputeView.vue): Vue screen · Primary user workspace for dispute analysis and responses · `frontend/src/views/DisputeView.vue`
- [Settings view](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/views/SettingsView.vue): Vue screen · Secondary configuration screen · `frontend/src/views/SettingsView.vue`
- [Chat panel](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/components/chat/ChatPanel.vue): UI component · Conversation-oriented presentation layer · `frontend/src/components/chat/ChatPanel.vue`
- [Strategy panel](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/components/strategy/StrategyPanel.vue): UI component · Structured fact/strategy/script/emotion presentation layer · `frontend/src/components/strategy/StrategyPanel.vue`
- [API client](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/api/index.js): frontend API · Client-side backend integration entrypoint · `frontend/src/api/index.js`
- [Dispute hook](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/frontend/src/composables/useDispute.js): state composable · 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](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/main.py): Python service · Backend application bootstrap and wiring · `backend/main.py`
- [Analyze router](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/routers/analyze.py): HTTP router · Primary analysis endpoint surface · `backend/routers/analyze.py`
- [Assisted controller](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/controllers/assisted_controller.py): orchestrator · Coordinates request handling and pipeline execution · `backend/controllers/assisted_controller.py`
- [Fact planner](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent1/fact_extractor.py): agent stage 1 · Extracts facts and plans rule matching · `backend/agents/agent1/fact_extractor.py`
- [Strategist](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent2/strategist.py): agent stage 2 · Generates dispute strategy from prior outputs · `backend/agents/agent2/strategist.py`
- [Script gen](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent3/script_generator.py): agent stage 3 · Produces response scripts and messaging · `backend/agents/agent3/script_generator.py`
- [Emotion monitor](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent4/emotion_monitor.py): agent stage 4 · Tracks tone and emotional risk · `backend/agents/agent4/emotion_monitor.py`
- [Reviewer](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/agents/agent5/reviewer.py): agent stage 5 · Reviews and revises the pipeline result · `backend/agents/agent5/reviewer.py`
- [LLM client](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tools/llm_client.py): model adapter · Shared abstraction for model calls · `backend/tools/llm_client.py`
- [Rule matcher](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tools/rule_matcher.py): rule engine · Deterministic and LLM-assisted rule identification · `backend/tools/rule_matcher.py`
- [Result cache](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/cache/result_cache.py): cache · Cached analysis outputs · `backend/cache/result_cache.py`
- [Fingerprinting](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/cache/fingerprint.py): cache key · Derives request and material identity · `backend/cache/fingerprint.py`
- [DB models](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/db/models.py): persistence · Durable backend state and relational models · `backend/db/models.py`
- [Review task](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/backend/tasks/review_task.py): worker job · Background review and revision processing · `backend/tasks/review_task.py`

### Rule Knowledge

Curated rule assets and offline ingestion/build jobs

- [Rule lexicon](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/data/rule_match_lexicon.json): knowledge base · Curated rule matching vocabulary · `data/rule_match_lexicon.json`
- [Lexicon build](https://github.com/6stephen-git/after-sales-e-commerce-assistant/blob/dev/scripts/build_rule_match_lexicon.py): ingestion script · Offline job that builds the rule lexicon · `scripts/build_rule_match_lexicon.py`

## Connections

- 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