# xixi48664-droid/eim-agent-qa architecture

> Architecture diagram of the GitHub repository xixi48664-droid/eim-agent-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xixi48664-droid/eim-agent-qa
- Repository: https://github.com/xixi48664-droid/eim-agent-qa

## Overview

1. **What this system is**
   - This repository implements an **AI-agent-based multimodal Q&A system for the electronics manufacturing domain**.
   - Architecturally it is split into a **Vue frontend**, a **Python backend API**, a **MySQL relational database**, and a **Qdrant vector store** for semantic retrieval.

2. **High-level request flow**
   - A user submits a query from the frontend.
   - The frontend calls backend HTTP APIs.
   - The backend routes the request through a service layer that either:
     - performs **authentication/account operations**, or
     - executes a **parameter/query workflow** for Q&A.
   - Data needed for responses is fetched from MySQL and, for search-like behavior, from Qdrant-backed knowledge data.

3. **Frontend subsystem**
   - The frontend is a **Vue 3 + Vite** single-page application.
   - It is split into:
     - `layouts/` for role-based page shells,
     - `views/common` for shared pages like login,
     - `views/user` for end-user query pages,
     - `views/admin` for administration pages,
     - `api/` for HTTP client wrappers,
     - `stores/` for auth/session state,
     - `router/` for navigation and access control.
   - This is the presentation boundary; it does not appear to contain business logic.

4. **Backend application boundary**
   - The backend is a **Python API service** organized as a classic layered architecture.
   - The main layers are:
     - `api/` controllers: HTTP endpoints,
     - `services/`: business logic,
     - `repositories/`: persistence access,
     - `entities/`: domain/data models,
     - `schemas/`: request/response contracts,
     - `core/`: config, security, and response helpers,
     - `utils/`: reusable crypto/token helpers.
   - This separation is important for the diagram: controllers do not directly talk to the database; they go through services and repositories.

5. **API surface and roles**
   - The backend exposes at least three functional areas:
     - `user_controller.py` for user/account operations,
     - `admin_controller.py` for admin management,
     - `qa_controller.py` for query/Q&A interactions.
   - On the frontend, this maps cleanly to:
     - login and user session flows,
     - admin user management screens,
     - user parameter/query screens.

6. **Authentication and authorization**
   - Authentication is handled in the backend via:
     - password utilities in `utils/password.py`,
     - token utilities in `utils/token.py`,
     - security helpers in `core/security.py`.
   - This suggests a **token-based login flow** with password verification and signed session tokens.
   - The frontend keeps auth state in `stores/auth.js` and attaches credentials through the API request layer.

7. **Persistence layer: MySQL**
   - The relational data store is **MySQL**.
   - The repository has dedicated database scripts under `database/mysql/`:
     - `schema.sql` for structure,
     - `init-data.sql` and `test-data.sql` for seed/test content,
     - `seed.py` for loading data.
   - Backend repositories map to the main business entities:
     - `user_repository.py`,
     - `component_repository.py`,
     - `history_repository.py`.
   - This indicates persistent storage for users, domain components, and operation/query history.

8. **Domain model**
   - The `entities/` package defines the core data objects:
     - `user.py`,
     - `component_info.py`,
     - `operation_log.py`.
   - These entities likely represent:
     - user accounts and roles,
     - knowledge/components used in the QA domain,
     - logs or audit/history records of operations and queries.
   - `schemas/` mirrors these for API payload validation and serialization.

9. **Q&A / retrieval subsystem**
   - The presence of `database/qdrant/collection-design.md` strongly suggests **Qdrant is used as a vector database** for semantic retrieval.
   - The `query_service.py` is the likely orchestration point that combines:
     - user input,
     - retrieval over indexed knowledge,
     - relational lookups in MySQL,
     - and response assembly for the Q&A result.
   - In the architecture diagram, Qdrant should be drawn as a separate knowledge/retrieval backend alongside MySQL, not inside the main relational database.

10. **Admin and operational management**
   - `services/admin_service.py` and `repositories/history_repository.py` imply an admin workflow beyond simple Q&A.
   - The admin UI includes a dedicated user management page, suggesting capabilities like:
     - user listing/maintenance,
     - inspection of logs or history,
     - possibly content/component management through `component_repository.py`.
   - This is a separate operational boundary from the end-user query path.

11. **Response and API conventions**
   - `core/response.py` indicates the backend likely standardizes API output shapes.
   - This is useful for diagramming because it means all controllers probably emit a consistent success/error envelope rather than ad hoc responses.
   - `schemas/` provide typed contracts between frontend and backend.

12. **Configuration and environment**
   - `backend/.env.example` and `core/config.py` indicate environment-driven configuration.
   - Typical configurable items here would include:
     - database connection details,
     - token/security settings,
     - service endpoints or keys for retrieval components.
   - This makes the deployment topology environment-sensitive, with runtime config separated from source code.

13. **Documentation and versioning**
   - The `docs/api/` directory contains at least two interface versions, `v1.0` and `v2.0`, showing that the API has evolved and may support versioned contracts.
   - `docs/design/` and `docs/test/` indicate the repo includes architecture and test documentation, useful for understanding expected interactions but not runtime components.

14. **How to draw the architecture**
   - A good diagram would show:
     - **Browser/User** → **Vue frontend**
     - **Frontend API client** → **Backend controllers**
     - **Controllers** → **Services**
     - **Services** → **Repositories / Qdrant / MySQL**
     - **Repositories** → **MySQL**
     - **Query service** → **Qdrant + MySQL**
     - **Admin/user services** → **MySQL**
   - The key architectural distinction is between the **transactional system of record** in MySQL and the **semantic retrieval layer** in Qdrant.

Main entry points: [`frontend/src`](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src) (Vue App), [`backend/app/api`](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/api) (Controllers), [`backend/app/services/admin_service.py`](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/admin_service.py) (Admin Service), [`backend/app/services/query_service.py`](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/query_service.py) (Query Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["Vue App<br/>frontend app"]
  node_layouts["Layouts<br/>ui shell"]
  node_views["Views<br/>pages"]
  node_client["API Client<br/>http client"]
  node_authstore["Auth Store<br/>state<br/>[auth.js]"]
  node_router["Router<br/>navigation<br/>[index.js]"]
end

subgraph group_backend["Backend"]
  node_controllers["Controllers<br/>api layer"]
  node_userctl["User API<br/>controller<br/>[user_controller.py]"]
  node_adminctl["Admin API<br/>controller"]
  node_qactl["Q&A API<br/>controller<br/>[qa_controller.py]"]
  node_services["Services<br/>business layer"]
  node_usersvc["User Service<br/>[user_service.py]"]
  node_adminsvc["Admin Service<br/>[admin_service.py]"]
  node_qasvc["Query Service<br/>[query_service.py]"]
  node_repos["Repositories<br/>persistence layer"]
  node_userrepo["User Repo<br/>[user_repository.py]"]
  node_componentrepo["Component Repo"]
  node_historyrepo["History Repo"]
  node_core["Core<br/>config/security"]
  node_utilauth["Auth Utils<br/>crypto/token"]
end

subgraph group_data["Data Stores"]
  node_mysql[("MySQL<br/>relational db")]
  node_qdrant[("Qdrant<br/>vector store")]
end

node_browser(("User<br/>actor"))

node_browser -->|"uses"| node_spa
node_spa -->|"renders"| node_layouts
node_spa -->|"navigates"| node_views
node_spa -->|"calls"| node_client
node_spa -->|"reads state"| node_authstore
node_spa -->|"routes through"| node_router
node_client -->|"requests"| node_controllers
node_authstore -->|"attaches auth"| node_client
node_router -->|"guards by"| node_authstore
node_controllers -->|"includes"| node_userctl
node_controllers -->|"includes"| node_adminctl
node_controllers -->|"includes"| node_qactl
node_userctl -->|"delegates"| node_usersvc
node_adminctl -->|"delegates"| node_adminsvc
node_qactl -->|"delegates"| node_qasvc
node_usersvc -->|"uses"| node_utilauth
node_usersvc -->|"persists via"| node_userrepo
node_adminsvc -->|"manages"| node_userrepo
node_adminsvc -->|"manages"| node_componentrepo
node_adminsvc -->|"reads"| node_historyrepo
node_qasvc -->|"retrieves"| node_componentrepo
node_qasvc -->|"logs"| node_historyrepo
node_userrepo -->|"reads/writes"| node_mysql
node_componentrepo -->|"reads/writes"| node_mysql
node_historyrepo -->|"reads/writes"| node_mysql
node_qasvc -->|"searches"| node_qdrant
node_controllers -->|"uses"| node_core
node_services -.->|"depends on"| node_repos

click node_spa "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src"
click node_layouts "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/layouts"
click node_views "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/views"
click node_client "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/api"
click node_authstore "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/frontend/src/stores/auth.js"
click node_router "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/frontend/src/router/index.js"
click node_controllers "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/api"
click node_userctl "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/user_controller.py"
click node_adminctl "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/admin_controller.py"
click node_qactl "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/qa_controller.py"
click node_services "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/services"
click node_usersvc "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/user_service.py"
click node_adminsvc "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/admin_service.py"
click node_qasvc "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/query_service.py"
click node_repos "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/repositories"
click node_userrepo "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/user_repository.py"
click node_componentrepo "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/component_repository.py"
click node_historyrepo "https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/history_repository.py"
click node_mysql "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/database/mysql"
click node_qdrant "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/database/qdrant"
click node_core "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/core"
click node_utilauth "https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/utils"

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_spa,node_layouts,node_views,node_client,node_authstore,node_router toneBlue
class node_controllers,node_userctl,node_adminctl,node_qactl,node_services,node_usersvc,node_adminsvc,node_qasvc,node_repos,node_userrepo,node_componentrepo,node_historyrepo,node_core,node_utilauth toneAmber
class node_mysql,node_qdrant toneMint
class node_browser toneNeutral
```

## Components

### Frontend

Vue 3 SPA presentation layer

- [Vue App](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src): frontend app · Vue 3 + Vite single-page application · `frontend/src`
- [Layouts](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/layouts): ui shell · Role-based page shells · `frontend/src/layouts`
- [Views](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/views): pages · Login, user query, and admin pages · `frontend/src/views`
- [API Client](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/frontend/src/api): http client · Frontend request wrappers and feature APIs · `frontend/src/api`
- [Auth Store](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/frontend/src/stores/auth.js): state · Session and authentication state · `frontend/src/stores/auth.js`
- [Router](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/frontend/src/router/index.js): navigation · Route access control and page switching · `frontend/src/router/index.js`

### Backend

Python API and business logic

- [Controllers](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/api): api layer · HTTP endpoints for user, admin, and Q&A · `backend/app/api`
- [User API](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/user_controller.py): controller · Account and login endpoints · `backend/app/api/user_controller.py`
- [Admin API](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/admin_controller.py): controller · Admin management endpoints · `backend/app/api/admin_controller.py`
- [Q&A API](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/api/qa_controller.py): controller · Query and parameter endpoints · `backend/app/api/qa_controller.py`
- [Services](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/services): business layer · Core application logic · `backend/app/services`
- [User Service](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/user_service.py): service · Authentication and account workflows · `backend/app/services/user_service.py`
- [Admin Service](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/admin_service.py): service · User and operational management workflows · `backend/app/services/admin_service.py`
- [Query Service](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/services/query_service.py): service · Retrieval and answer assembly workflow · `backend/app/services/query_service.py`
- [Repositories](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/repositories): persistence layer · Database access boundary · `backend/app/repositories`
- [User Repo](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/user_repository.py): repository · User account persistence · `backend/app/repositories/user_repository.py`
- [Component Repo](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/component_repository.py): repository · Domain component and knowledge record persistence · `backend/app/repositories/component_repository.py`
- [History Repo](https://github.com/xixi48664-droid/eim-agent-qa/blob/main/backend/app/repositories/history_repository.py): repository · Operation and query history persistence · `backend/app/repositories/history_repository.py`
- [Core](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/core): config/security · Configuration, response envelope, and security helpers · `backend/app/core`
- [Auth Utils](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/backend/app/utils): crypto/token · Password verification and token helpers · `backend/app/utils`

### Data Stores

Relational and vector backends

- [MySQL](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/database/mysql): relational db · System of record for users, components, and history · `database/mysql`
- [Qdrant](https://github.com/xixi48664-droid/eim-agent-qa/tree/main/database/qdrant): vector store · Semantic retrieval and knowledge search backend · `database/qdrant`

### Other components

- **User**: actor · End user or admin using the app

## Connections

- User → Vue App: uses · User interacts with the SPA
- Vue App → Layouts: renders · Page shell composition
- Vue App → Views: navigates · Route-driven page content
- Vue App → API Client: calls · Feature APIs over HTTP
- Vue App → Auth Store: reads state · Session and token state
- Vue App → Router: routes through · Navigation and access control
- API Client → Controllers: requests · HTTP API calls
- Auth Store → API Client: attaches auth · Credentials and session context
- Router → Auth Store: guards by · Access decisions based on auth state
- Controllers → User API: includes · User/account endpoints
- Controllers → Admin API: includes · Admin endpoints
- Controllers → Q&A API: includes · Q&A endpoints
- User API → User Service: delegates · Login and account flows
- Admin API → Admin Service: delegates · Admin management flows
- Q&A API → Query Service: delegates · Query and answer flows
- User Service → Auth Utils: uses · Password and token operations
- User Service → User Repo: persists via · User records
- Admin Service → User Repo: manages · Admin user maintenance
- Admin Service → Component Repo: manages · Domain knowledge/component data
- Admin Service → History Repo: reads · Operational and audit history
- Query Service → Component Repo: retrieves · Domain knowledge data
- Query Service → History Repo: logs · Query and operation history
- User Repo → MySQL: reads/writes · Relational persistence
- Component Repo → MySQL: reads/writes · Relational persistence
- History Repo → MySQL: reads/writes · Relational persistence
- Query Service → Qdrant: searches · Semantic retrieval over vector index
- Controllers → Core: uses · Config, response envelopes, and security helpers
- Services → Repositories: depends on · Business logic uses persistence boundary
