# pranavishal/prox-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/pranavishal/prox-challenge
- Repository: https://github.com/pranavishal/prox-challenge

## Overview

1. **Product shape**
   - This is a **Next.js App Router** application for a welding assistant.
   - The main user experience is a **chat interface** that answers technical questions and can also diagnose uploaded weld photos.
   - The app is intentionally split between **natural-language answers** and **interactive artifacts** such as calculators, diagrams, and troubleshooting views.

2. **Primary request flow**
   - User input starts in the client chat UI.
   - Messages are sent to the server API at `src/app/api/chat/route.ts`.
   - That route orchestrates an **agent loop** with Anthropic Claude, including tool calls and streaming output.
   - The response comes back as **streamed text plus optional artifact payloads**, which the client renders in separate regions.

3. **Agent core**
   - The agent behavior is defined by `src/agent/system-prompt.ts`.
   - The prompt controls:
     - when the model should use tools,
     - when it should generate an artifact,
     - how it should present technical answers.
   - `src/agent/stream-parser.ts` extracts artifact markup from Claude’s streaming output so text can keep flowing while artifact code is captured separately.

4. **Tool-based knowledge access**
   - The repo does not rely on generic RAG or a vector database.
   - Instead, the agent uses **six structured tools** in `src/agent/tools/`:
     - duty cycle lookup
     - polarity lookup
     - settings recommendation
     - troubleshooting traversal
     - specs lookup
     - manual image retrieval
   - `src/agent/tools/index.ts` acts as the tool registry and central export point.

5. **Knowledge base boundary**
   - The authoritative domain data lives in committed JSON files under `data/`.
   - Each file maps to a specific task:
     - `duty-cycle.json` for exact amperage/voltage duty cycle tables
     - `polarity.json` for cable/socket setup
     - `settings.json` for process/material/thickness recommendations
     - `troubleshooting.json` for symptom → cause → fix relationships
     - `specs.json` for machine specification lookup
     - `manual-images.json` for keyword-based retrieval of manual page images
   - This is the main separation between **agent logic** and **domain knowledge**.

6. **Troubleshooting as a graph**
   - The troubleshooting data is modeled as structured relationships rather than flat text.
   - The agent can traverse from a symptom to multiple causes and then to specific fixes.
   - This makes the diagnostic flow deterministic and easy to extend without changing the agent code.

7. **Visual/manual image retrieval**
   - The app includes extracted manual page images under `public/manual-images/`.
   - `src/agent/tools/manual-images.ts` uses `data/manual-images.json` to match user questions to relevant pages.
   - This supports answers where the correct response is partly visual, such as polarity wiring, front-panel settings, or weld defect examples.

8. **Interactive artifact system**
   - Claude can emit embedded artifact markup in its response.
   - `StreamParser` recognizes those artifact blocks and separates them from normal text.
   - Artifacts are rendered in `src/components/artifacts/ArtifactRenderer.tsx` inside a sandboxed iframe.

9. **Artifact runtime boundary**
   - `public/artifact-runtime.html` is a prebuilt runtime for rendering those artifacts.
   - It includes the client-side stack needed inside the sandbox, including React, Tailwind styling, and Recharts support.
   - This keeps interactive UI generation isolated from the main app shell.

10. **Client UI structure**
   - `src/components/chat/` contains the user-facing chat experience:
     - `ChatInterface.tsx` for orchestration
     - `InputBar.tsx` for composing prompts
     - `Message.tsx` for rendering messages
   - `src/components/artifacts/` handles the side-panel artifact display.
   - Shared UI primitives live under `src/components/ui/`.

11. **App shell and routing**
   - `src/app/page.tsx` is the main entry page for the assistant.
   - `src/app/layout.tsx` provides the global layout.
   - `src/app/globals.css` and the Tailwind/shadcn setup define the visual system.
   - The app is lightweight on routes; the main architecture centers on a single interactive assistant page plus the chat API.

12. **External dependency boundary**
   - The only major runtime dependency that materially affects architecture is the **Anthropic API** via `@anthropic-ai/sdk`.
   - The server-side chat route is the integration point between the app’s structured knowledge and Claude’s reasoning.
   - Everything else is local and self-contained: the manual-derived datasets, UI, and artifact runtime.

13. **Repo-level design intent**
   - The architecture is optimized for a **small, precise technical domain** where exact lookup is more important than semantic search.
   - Knowledge extraction happened ahead of time; the runtime system is mostly:
     - tool routing,
     - response streaming,
     - artifact rendering,
     - and UI presentation.
   - That makes the main diagram naturally split into three layers: **client chat UI**, **server agent/tools**, and **static knowledge/artifact assets**.

Main entry points: [`src/agent/tools/index.ts`](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/index.ts) (Tool registry), [`src/app/api/chat/route.ts`](https://github.com/pranavishal/prox-challenge/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/components/chat/ChatInterface.tsx`](https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/ChatInterface.tsx) (Chat interface), [`src/agent/tools/manual-images.ts`](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/manual-images.ts) (Manual images)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_page["Assistant page<br/>Next.js page<br/>[page.tsx]"]
  node_layout["Root layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_styles["Global styles<br/>CSS<br/>[globals.css]"]
end

subgraph group_client["Client UI"]
  node_chat["Chat interface<br/>client shell<br/>[ChatInterface.tsx]"]
  node_input["Input bar<br/>chat input<br/>[InputBar.tsx]"]
  node_message["Message view<br/>chat render<br/>[Message.tsx]"]
  node_artifact_ui["Artifact panel<br/>artifact host"]
end

subgraph group_server["Agent server"]
  node_chat_api["Chat API<br/>route handler<br/>[route.ts]"]
  node_prompt["System prompt<br/>agent prompt<br/>[system-prompt.ts]"]
  node_parser["Stream parser<br/>artifact parser<br/>[stream-parser.ts]"]
  node_tools_index["Tool registry<br/>tool index<br/>[index.ts]"]
  node_duty["Duty cycle<br/>lookup tool<br/>[duty-cycle.ts]"]
  node_polarity["Polarity lookup<br/>lookup tool<br/>[polarity.ts]"]
  node_settings["Settings recommender<br/>lookup tool<br/>[settings.ts]"]
  node_troubleshoot["Troubleshooting<br/>graph tool<br/>[troubleshooting.ts]"]
  node_specs["Specs lookup<br/>lookup tool<br/>[specs.ts]"]
  node_manuals["Manual images<br/>image lookup<br/>[manual-images.ts]"]
end

subgraph group_knowledge["Knowledge assets"]
  node_duty_data[("Duty tables<br/>domain json<br/>[duty-cycle.json]")]
  node_polarity_data[("Polarity data<br/>domain json<br/>[polarity.json]")]
  node_settings_data[("Settings data<br/>domain json<br/>[settings.json]")]
  node_trouble_data[("Trouble graph<br/>domain graph")]
  node_specs_data[("Specs data<br/>domain json<br/>[specs.json]")]
  node_manual_index[("Manual index<br/>image map<br/>[manual-images.json]")]
  node_manual_imgs["Manual pages<br/>image assets"]
end

subgraph group_runtime["Artifact runtime"]
  node_artifact_rt["Artifact runtime<br/>sandbox runtime"]
end

node_page -->|"mounts"| node_chat
node_layout -->|"wraps"| node_page
node_styles -->|"styles"| node_page
node_chat -->|"contains"| node_input
node_chat -->|"contains"| node_message
node_chat -->|"contains"| node_artifact_ui
node_input -->|"sends"| node_chat_api
node_message -.->|"reads stream"| node_chat_api
node_chat_api -->|"loads"| node_prompt
node_chat_api -->|"parses"| node_parser
node_chat_api -->|"invokes"| node_tools_index
node_tools_index -->|"exports"| node_duty
node_tools_index -->|"exports"| node_polarity
node_tools_index -->|"exports"| node_settings
node_tools_index -->|"exports"| node_troubleshoot
node_tools_index -->|"exports"| node_specs
node_tools_index -->|"exports"| node_manuals
node_duty -->|"reads"| node_duty_data
node_polarity -->|"reads"| node_polarity_data
node_settings -->|"reads"| node_settings_data
node_troubleshoot -->|"reads"| node_trouble_data
node_specs -->|"reads"| node_specs_data
node_manuals -->|"reads"| node_manual_index
node_manuals -->|"returns"| node_manual_imgs
node_artifact_ui -->|"embeds"| node_artifact_rt
node_parser -->|"feeds"| node_artifact_ui
node_chat_api -.->|"targets"| node_artifact_rt

click node_page "https://github.com/pranavishal/prox-challenge/blob/main/src/app/page.tsx"
click node_layout "https://github.com/pranavishal/prox-challenge/blob/main/src/app/layout.tsx"
click node_styles "https://github.com/pranavishal/prox-challenge/blob/main/src/app/globals.css"
click node_chat "https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/ChatInterface.tsx"
click node_input "https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/InputBar.tsx"
click node_message "https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/Message.tsx"
click node_artifact_ui "https://github.com/pranavishal/prox-challenge/blob/main/src/components/artifacts/ArtifactRenderer.tsx"
click node_chat_api "https://github.com/pranavishal/prox-challenge/blob/main/src/app/api/chat/route.ts"
click node_prompt "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/system-prompt.ts"
click node_parser "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/stream-parser.ts"
click node_tools_index "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/index.ts"
click node_duty "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/duty-cycle.ts"
click node_polarity "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/polarity.ts"
click node_settings "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/settings.ts"
click node_troubleshoot "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/troubleshooting.ts"
click node_specs "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/specs.ts"
click node_manuals "https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/manual-images.ts"
click node_artifact_rt "https://github.com/pranavishal/prox-challenge/blob/main/public/artifact-runtime.html"
click node_duty_data "https://github.com/pranavishal/prox-challenge/blob/main/data/duty-cycle.json"
click node_polarity_data "https://github.com/pranavishal/prox-challenge/blob/main/data/polarity.json"
click node_settings_data "https://github.com/pranavishal/prox-challenge/blob/main/data/settings.json"
click node_trouble_data "https://github.com/pranavishal/prox-challenge/blob/main/data/troubleshooting.json"
click node_specs_data "https://github.com/pranavishal/prox-challenge/blob/main/data/specs.json"
click node_manual_index "https://github.com/pranavishal/prox-challenge/blob/main/data/manual-images.json"
click node_manual_imgs "https://github.com/pranavishal/prox-challenge/tree/main/public/manual-images"

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_page,node_layout,node_styles toneBlue
class node_chat,node_input,node_message,node_artifact_ui toneAmber
class node_chat_api,node_prompt,node_parser,node_tools_index,node_duty,node_polarity,node_settings,node_troubleshoot,node_specs,node_manuals toneMint
class node_duty_data,node_polarity_data,node_settings_data,node_trouble_data,node_specs_data,node_manual_index,node_manual_imgs toneRose
class node_artifact_rt toneIndigo
```

## Components

### App shell

Next.js entry points and global styling.

- [Assistant page](https://github.com/pranavishal/prox-challenge/blob/main/src/app/page.tsx): Next.js page · Main entry page for the welding assistant. · `src/app/page.tsx`
- [Root layout](https://github.com/pranavishal/prox-challenge/blob/main/src/app/layout.tsx): Next.js layout · Global app shell and document structure. · `src/app/layout.tsx`
- [Global styles](https://github.com/pranavishal/prox-challenge/blob/main/src/app/globals.css): CSS · Global visual system and base styling. · `src/app/globals.css`

### Client UI

Chat experience and artifact presentation in the browser.

- [Chat interface](https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/ChatInterface.tsx): client shell · Coordinates the user-facing assistant experience. · `src/components/chat/ChatInterface.tsx`
- [Input bar](https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/InputBar.tsx): chat input · Composes and submits user prompts. · `src/components/chat/InputBar.tsx`
- [Message view](https://github.com/pranavishal/prox-challenge/blob/main/src/components/chat/Message.tsx): chat render · Renders assistant and user messages in the thread. · `src/components/chat/Message.tsx`
- [Artifact panel](https://github.com/pranavishal/prox-challenge/blob/main/src/components/artifacts/ArtifactRenderer.tsx): artifact host · Displays interactive artifacts alongside text responses. · `src/components/artifacts/ArtifactRenderer.tsx`

### Agent server

Chat API plus prompt, parsing, and tool orchestration.

- [Chat API](https://github.com/pranavishal/prox-challenge/blob/main/src/app/api/chat/route.ts): route handler · Server endpoint that orchestrates the agent loop and streaming response. · `src/app/api/chat/route.ts`
- [System prompt](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/system-prompt.ts): agent prompt · Controls tool use, artifact generation, and answer style. · `src/agent/system-prompt.ts`
- [Stream parser](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/stream-parser.ts): artifact parser · Separates streamed text from embedded artifact markup. · `src/agent/stream-parser.ts`
- [Tool registry](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/index.ts): tool index · Central export and registration point for agent tools. · `src/agent/tools/index.ts`
- [Duty cycle](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/duty-cycle.ts): lookup tool · Retrieves exact amperage and voltage duty-cycle tables. · `src/agent/tools/duty-cycle.ts`
- [Polarity lookup](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/polarity.ts): lookup tool · Returns cable and socket polarity setup guidance. · `src/agent/tools/polarity.ts`
- [Settings recommender](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/settings.ts): lookup tool · Finds process, material, and thickness recommendations. · `src/agent/tools/settings.ts`
- [Troubleshooting](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/troubleshooting.ts): graph tool · Traverses symptom, cause, and fix relationships. · `src/agent/tools/troubleshooting.ts`
- [Specs lookup](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/specs.ts): lookup tool · Retrieves machine specification data. · `src/agent/tools/specs.ts`
- [Manual images](https://github.com/pranavishal/prox-challenge/blob/main/src/agent/tools/manual-images.ts): image lookup · Matches questions to relevant manual page images. · `src/agent/tools/manual-images.ts`

### Knowledge assets

Committed domain data and extracted manual resources.

- [Duty tables](https://github.com/pranavishal/prox-challenge/blob/main/data/duty-cycle.json): domain json · Authoritative duty-cycle lookup data. · `data/duty-cycle.json`
- [Polarity data](https://github.com/pranavishal/prox-challenge/blob/main/data/polarity.json): domain json · Authoritative polarity and wiring data. · `data/polarity.json`
- [Settings data](https://github.com/pranavishal/prox-challenge/blob/main/data/settings.json): domain json · Authoritative process and material recommendation data. · `data/settings.json`
- [Trouble graph](https://github.com/pranavishal/prox-challenge/blob/main/data/troubleshooting.json): domain graph · Structured symptom-to-cause-to-fix knowledge. · `data/troubleshooting.json`
- [Specs data](https://github.com/pranavishal/prox-challenge/blob/main/data/specs.json): domain json · Authoritative machine specification data. · `data/specs.json`
- [Manual index](https://github.com/pranavishal/prox-challenge/blob/main/data/manual-images.json): image map · Keyword index for manual-page image retrieval. · `data/manual-images.json`
- [Manual pages](https://github.com/pranavishal/prox-challenge/tree/main/public/manual-images): image assets · Extracted manual page images used for visual answers. · `public/manual-images`

### Artifact runtime

Sandboxed browser runtime for interactive artifacts.

- [Artifact runtime](https://github.com/pranavishal/prox-challenge/blob/main/public/artifact-runtime.html): sandbox runtime · Prebuilt iframe runtime for interactive artifact execution. · `public/artifact-runtime.html`

## Connections

- Assistant page → Chat interface: mounts · The main page renders the assistant experience.
- Root layout → Assistant page: wraps · Root layout provides the outer app shell.
- Global styles → Assistant page: styles · Global CSS shapes the interface.
- Chat interface → Input bar: contains · Chat interface includes the prompt composer.
- Chat interface → Message view: contains · Chat interface renders the conversation stream.
- Chat interface → Artifact panel: contains · Chat interface hosts artifact output.
- Input bar → Chat API: sends · User prompts are posted to the chat endpoint.
- Message view → Chat API: reads stream · Messages reflect streamed assistant output.
- Chat API → System prompt: loads · The route uses the system prompt to steer the model.
- Chat API → Stream parser: parses · Streaming output is split into text and artifact payloads.
- Chat API → Tool registry: invokes · The route orchestrates structured tool calls.
- Tool registry → Duty cycle: exports · Registry exposes duty-cycle lookup.
- Tool registry → Polarity lookup: exports · Registry exposes polarity lookup.
- Tool registry → Settings recommender: exports · Registry exposes settings recommendations.
- Tool registry → Troubleshooting: exports · Registry exposes troubleshooting traversal.
- Tool registry → Specs lookup: exports · Registry exposes machine specs lookup.
- Tool registry → Manual images: exports · Registry exposes manual image retrieval.
- Duty cycle → Duty tables: reads · Tool queries the duty-cycle dataset.
- Polarity lookup → Polarity data: reads · Tool queries the polarity dataset.
- Settings recommender → Settings data: reads · Tool queries the settings dataset.
- Troubleshooting → Trouble graph: reads · Tool traverses the troubleshooting graph data.
- Specs lookup → Specs data: reads · Tool queries the specs dataset.
- Manual images → Manual index: reads · Tool matches questions against the manual image index.
- Manual images → Manual pages: returns · Tool surfaces matching manual page images.
- Artifact panel → Artifact runtime: embeds · Artifacts render inside the sandboxed runtime iframe.
- Stream parser → Artifact panel: feeds · Parsed artifact blocks are sent to the artifact renderer.
- Chat API → Artifact runtime: targets · Artifact markup is designed for the runtime environment.
