How xixi48664-droid/eim-agent-qa works
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: src Vue App · api Controllers · admin_service.py Admin Service · query_service.py Query Service
Components 23
Frontend
Vue 3 SPA presentation layer
- Vue App · Vue 3 + Vite single-page application
frontend/src - Layouts · Role-based page shells
frontend/src/layouts - Views · Login, user query, and admin pages
frontend/src/views - API Client · Frontend request wrappers and feature APIs
frontend/src/api - Auth Store · Session and authentication state
frontend/src/stores/auth.js - Router · Route access control and page switching
frontend/src/router/index.js
Backend
Python API and business logic
- Controllers · HTTP endpoints for user, admin, and Q&A
backend/app/api - User API · Account and login endpoints
backend/app/api/user_controller.py - Admin API · Admin management endpoints
backend/app/api/admin_controller.py - Q&A API · Query and parameter endpoints
backend/app/api/qa_controller.py - Services · Core application logic
backend/app/services - User Service · Authentication and account workflows
backend/app/services/user_service.py - Admin Service · User and operational management workflows
backend/app/services/admin_service.py - Query Service · Retrieval and answer assembly workflow
backend/app/services/query_service.py - Repositories · Database access boundary
backend/app/repositories - User Repo · User account persistence
backend/app/repositories/user_repository.py - Component Repo · Domain component and knowledge record persistence
backend/app/repositories/component_repository.py - History Repo · Operation and query history persistence
backend/app/repositories/history_repository.py - Core · Configuration, response envelope, and security helpers
backend/app/core - Auth Utils · Password verification and token helpers
backend/app/utils
Data Stores
Relational and vector backends
Other components
- User · End user or admin using the app
Connections 28
- 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