# niraj12chaudhary/field-service-ai-assistant architecture

> Architecture diagram of the GitHub repository niraj12chaudhary/field-service-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niraj12chaudhary/field-service-ai-assistant
- Repository: https://github.com/niraj12chaudhary/field-service-ai-assistant

## Overview

#### Purpose and entry points

Field-Service Assistant is a local chat system for technicians. It answers only from a Markdown knowledge base and performs controlled work-order actions through Gemini function calling. The backend entry point is `backend/main.py`; the browser entry is `frontend/src/main.jsx`, rendering the chat UI in `frontend/src/App.jsx`.

#### API and session boundary

FastAPI exposes health and chat APIs from `backend/main.py`. Chat requests are associated with in-memory conversation sessions, allowing follow-up references such as “mark it complete” to retain prior context. The React client sends requests through the Vite development proxy in `frontend/vite.config.js`, avoiding browser-to-backend CORS handling during local development.

#### Agent orchestration

`backend/agent.py` owns the Gemini interaction loop: it supplies the system instructions, conversation history, and declared tools; receives model function calls; executes server-side tool implementations; then returns tool results to Gemini for a final natural-language response. Gemini is an external runtime dependency, authenticated by `GEMINI_API_KEY` in `backend/.env`.

Key boundaries:
- The model proposes actions; it does not directly mutate data.
- Tool results, not model claims, determine whether an operation succeeds.
- Knowledge responses are routed through grounded search rather than open-ended inference.

#### Enforced work-order tool layer

`backend/tools.py` is the authorization and business-rule boundary. It implements lookup, technician-scoped listing, status updates, note creation, escalation, and knowledge search. It enforces ownership for the fixed logged-in technician and validates the allowed status progression (`Open → In Progress → On Hold → Completed`) in code.

Tool arguments and work-order shapes are validated through Pydantic models in `backend/models.py`. This separation prevents prompt injection or malformed function arguments from bypassing policy enforcement.

#### Persistence and domain data

`backend/data_store.py` provides raw JSON read/write access and deliberately contains no business rules. Work orders are persisted in `backend/data/work_orders.json`; records include assignment, status, plus application-added note and escalation fields. The current implementation is file-backed and suitable for local/single-process use rather than concurrent or durable multi-instance deployment.

#### Knowledge grounding path

`backend/knowledge.py` searches the reference content in `backend/data/knowledge.md`. The `search_knowledge` tool returns an explicit not-found result when the source does not cover a question, allowing the agent to produce a fixed non-speculative response instead of inventing policy or procedure.

#### Frontend runtime

The frontend is a minimal React/Vite single-page chat client. `frontend/src/App.jsx` manages the message list, user input, API submission, and display of assistant responses. It has no separate authentication layer: technician identity is currently established server-side as part of the backend’s controlled execution context.

Main entry points: [`backend/agent.py`](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/agent.py) (Agent Loop), [`backend/tools.py`](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/tools.py) (Tool Policy Layer), [`backend/main.py`](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/main.py) (FastAPI API), [`frontend/src/App.jsx`](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/src/App.jsx) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Technician Browser<br/>user client"))
  node_frontend_entry["React Entry<br/>React bootstrap<br/>[main.jsx]"]
  node_chat_ui["Chat UI<br/>React component<br/>[App.jsx]"]
  node_vite_proxy["Vite Dev Proxy<br/>development proxy<br/>[vite.config.js]"]
end

subgraph group_backend["Backend"]
  node_api{{"FastAPI API<br/>API and session boundary<br/>[main.py]"}}
  node_agent["Agent Loop<br/>Gemini orchestration<br/>[agent.py]"]
  node_tools{{"Tool Policy Layer<br/>authorized tool implementations<br/>[tools.py]"}}
  node_models["Pydantic Models<br/>argument and domain validation<br/>[models.py]"]
  node_data_store["JSON Data Store<br/>raw persistence access<br/>[data_store.py]"]
  node_knowledge_search["Knowledge Search<br/>grounded Markdown search<br/>[knowledge.py]"]
  node_session_memory["Conversation Sessions<br/>in-memory state<br/>[main.py]"]
  node_gemini_config["Gemini API Key<br/>runtime credential"]
end

subgraph group_data["Local Data"]
  node_work_orders[("Work Orders<br/>JSON file<br/>[work_orders.json]")]
  node_knowledge_base["Knowledge Base<br/>Markdown reference<br/>[knowledge.md]"]
end

node_gemini{{"Gemini<br/>external model runtime"}}

node_browser -->|"loads"| node_frontend_entry
node_frontend_entry -->|"renders"| node_chat_ui
node_chat_ui -->|"chat requests"| node_vite_proxy
node_vite_proxy -->|"forwards / API"| node_api
node_api -->|"reads and updates"| node_session_memory
node_api -->|"chat request and history"| node_agent
node_agent -->|"instructions, history, tools"| node_gemini
node_gemini -->|"function calls or response"| node_agent
node_agent -->|"executes proposed calls"| node_tools
node_tools -->|"validates arguments and shapes"| node_models
node_tools -->|"authorized work-order operations"| node_data_store
node_data_store -->|"reads and writes"| node_work_orders
node_tools -->|"search_knowledge"| node_knowledge_search
node_knowledge_search -->|"searches"| node_knowledge_base
node_tools -->|"tool results"| node_agent
node_gemini_config -.->|"authenticates"| node_gemini
node_agent -->|"final answer"| node_api
node_api -->|"assistant response"| node_chat_ui

click node_frontend_entry "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/src/main.jsx"
click node_chat_ui "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/src/App.jsx"
click node_vite_proxy "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/vite.config.js"
click node_api "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/main.py"
click node_agent "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/agent.py"
click node_tools "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/tools.py"
click node_models "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/models.py"
click node_data_store "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data_store.py"
click node_knowledge_search "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/knowledge.py"
click node_work_orders "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data/work_orders.json"
click node_knowledge_base "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data/knowledge.md"
click node_session_memory "https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/main.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_browser,node_frontend_entry,node_chat_ui,node_vite_proxy toneBlue
class node_api,node_agent,node_tools,node_models,node_data_store,node_knowledge_search,node_session_memory,node_gemini_config toneAmber
class node_work_orders,node_knowledge_base toneMint
class node_gemini toneNeutral
```

## Components

### Frontend

- **Technician Browser**: user client
- [React Entry](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/src/main.jsx): React bootstrap · `frontend/src/main.jsx`
- [Chat UI](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/src/App.jsx): React component · Manages messages, input, submission, and responses. · `frontend/src/App.jsx`
- [Vite Dev Proxy](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/frontend/vite.config.js): development proxy · Forwards local API requests without browser CORS handling. · `frontend/vite.config.js`

### Backend

- [FastAPI API](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/main.py): API and session boundary · Exposes health and chat APIs with in-memory conversation sessions. · `backend/main.py`
- [Agent Loop](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/agent.py): Gemini orchestration · Runs model/tool exchanges and returns the final response. · `backend/agent.py`
- [Tool Policy Layer](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/tools.py): authorized tool implementations · Enforces technician ownership and work-order rules. · `backend/tools.py`
- [Pydantic Models](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/models.py): argument and domain validation · `backend/models.py`
- [JSON Data Store](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data_store.py): raw persistence access · Reads and writes JSON without business rules. · `backend/data_store.py`
- [Knowledge Search](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/knowledge.py): grounded Markdown search · Returns explicit not-found results for unsupported questions. · `backend/knowledge.py`
- [Conversation Sessions](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/main.py): in-memory state · Retains prior chat context for follow-up requests. · `backend/main.py`
- **Gemini API Key**: runtime credential

### Local Data

- [Work Orders](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data/work_orders.json): JSON file · File-backed local work-order records. · `backend/data/work_orders.json`
- [Knowledge Base](https://github.com/niraj12chaudhary/field-service-ai-assistant/blob/main/backend/data/knowledge.md): Markdown reference · `backend/data/knowledge.md`

### Other components

- **Gemini**: external model runtime · Proposes function calls and generates grounded responses.

## Connections

- Technician Browser → React Entry: loads
- React Entry → Chat UI: renders
- Chat UI → Vite Dev Proxy: chat requests
- Vite Dev Proxy → FastAPI API: forwards / API
- FastAPI API → Conversation Sessions: reads and updates
- FastAPI API → Agent Loop: chat request and history
- Agent Loop → Gemini: instructions, history, tools
- Gemini → Agent Loop: function calls or response
- Agent Loop → Tool Policy Layer: executes proposed calls
- Tool Policy Layer → Pydantic Models: validates arguments and shapes
- Tool Policy Layer → JSON Data Store: authorized work-order operations
- JSON Data Store → Work Orders: reads and writes
- Tool Policy Layer → Knowledge Search: search_knowledge
- Knowledge Search → Knowledge Base: searches
- Tool Policy Layer → Agent Loop: tool results
- Gemini API Key → Gemini: authenticates
- Agent Loop → FastAPI API: final answer
- FastAPI API → Chat UI: assistant response