# trxu05/fullstack-ai-agent architecture

> Architecture diagram of the GitHub repository trxu05/fullstack-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trxu05/fullstack-ai-agent
- Repository: https://github.com/trxu05/fullstack-ai-agent

## Overview

StudyBoard combines a course/task/note dashboard with a session-aware tutor. A learner uses the web dashboard to create a session, view and edit the board, and chat; the Spring gateway forwards those requests to FastAPI, whose agent selects OpenAI tool-calling or a rules fallback. Tools retrieve note passages, produce plans/explanations/quizzes/flashcards, and mutate board data, persisted in SQLite. README documents the broader tutor capabilities; unsampled UI and gateway details are represented only where documented or shown.

Main entry points: [`python-agent/agent.py`](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/agent.py) (Chat orchestrator), [`python-agent/board.py`](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/board.py) (Board state), [`python-agent/main.py`](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/main.py) (Agent API), [`python-agent/tools.py`](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/tools.py) (Tutor tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Study dashboard<br/>[page.tsx]"]
end

subgraph group_gateway["API gateway"]
  node_gateway_app["Spring gateway"]
  node_session_api["Session API"]
end

subgraph group_agent["Tutor runtime"]
  node_fastapi["Agent API<br/>[main.py]"]
  node_chat_agent["Chat orchestrator<br/>[agent.py]"]
  node_tutor_tools["Tutor tools<br/>[tools.py]"]
  node_note_search["Note retrieval<br/>[retrieve.py]"]
end

subgraph group_data["Board data"]
  node_board_state["Board state<br/>[board.py]"]
  node_sqlite[("SQLite boards<br/>[store.py]")]
end

node_learner(("Learner"))
node_openai{{"OpenAI API"}}

node_learner -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_session_api
node_session_api -->|"forwards requests"| node_fastapi
node_fastapi -->|"loads and updates"| node_board_state
node_fastapi -->|"runs chat"| node_chat_agent
node_chat_agent -->|"dispatches tools"| node_tutor_tools
node_tutor_tools -->|"retrieves passages"| node_note_search
node_tutor_tools -->|"reads and mutates"| node_board_state
node_chat_agent -->|"persists changes"| node_board_state
node_board_state -->|"loads and saves"| node_sqlite
node_chat_agent -.->|"calls tool API"| node_openai

click node_dashboard "https://github.com/trxu05/fullstack-ai-agent/blob/main/web/src/app/page.tsx"
click node_gateway_app "https://github.com/trxu05/fullstack-ai-agent/blob/main/java-api/src/main/java/com/trxu05/agentapi/AgentApiApplication.java"
click node_session_api "https://github.com/trxu05/fullstack-ai-agent/blob/main/java-api/src/main/java/com/trxu05/agentapi/SessionController.java"
click node_fastapi "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/main.py"
click node_chat_agent "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/agent.py"
click node_tutor_tools "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/tools.py"
click node_note_search "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/retrieve.py"
click node_board_state "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/board.py"
click node_sqlite "https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/store.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_dashboard toneBlue
class node_gateway_app,node_session_api toneAmber
class node_fastapi,node_chat_agent,node_tutor_tools,node_note_search,node_openai toneMint
class node_board_state,node_sqlite toneRose
class node_learner toneIndigo
```

## Components

### Dashboard

- [Study dashboard](https://github.com/trxu05/fullstack-ai-agent/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`

### API gateway

- [Spring gateway](https://github.com/trxu05/fullstack-ai-agent/blob/main/java-api/src/main/java/com/trxu05/agentapi/AgentApiApplication.java): `java-api/src/main/java/com/trxu05/agentapi/AgentApiApplication.java`
- [Session API](https://github.com/trxu05/fullstack-ai-agent/blob/main/java-api/src/main/java/com/trxu05/agentapi/SessionController.java): `java-api/src/main/java/com/trxu05/agentapi/SessionController.java`

### Tutor runtime

- [Agent API](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/main.py): `python-agent/main.py`
- [Chat orchestrator](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/agent.py): `python-agent/agent.py`
- [Tutor tools](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/tools.py): `python-agent/tools.py`
- [Note retrieval](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/retrieve.py): `python-agent/retrieve.py`

### Board data

- [Board state](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/board.py): `python-agent/board.py`
- [SQLite boards](https://github.com/trxu05/fullstack-ai-agent/blob/main/python-agent/store.py): `python-agent/store.py`

### Other components

- **Learner**
- **OpenAI API**

## Connections

- Learner → Study dashboard: uses (evidence: `README.md`)
- Study dashboard → Session API: requests (evidence: `web/src/app/page.tsx`)
- Session API → Agent API: forwards requests (evidence: `java-api/src/main/java/com/trxu05/agentapi/SessionController.java`)
- Agent API → Board state: loads and updates (evidence: `python-agent/main.py`)
- Agent API → Chat orchestrator: runs chat (evidence: `python-agent/main.py`)
- Chat orchestrator → Tutor tools: dispatches tools (evidence: `python-agent/agent.py`)
- Tutor tools → Note retrieval: retrieves passages (evidence: `python-agent/tools.py`)
- Tutor tools → Board state: reads and mutates (evidence: `python-agent/tools.py`)
- Chat orchestrator → Board state: persists changes (evidence: `python-agent/agent.py`)
- Board state → SQLite boards: loads and saves (evidence: `python-agent/board.py`)
- Chat orchestrator → OpenAI API: calls tool API (evidence: `python-agent/agent.py`)