How pranavishal/prox-challenge works
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: index.ts Tool registry · route.ts Chat API · ChatInterface.tsx Chat interface · manual-images.ts Manual images
Components 25
App shell
Next.js entry points and global styling.
- Assistant page · Main entry page for the welding assistant.
src/app/page.tsx - Root layout · Global app shell and document structure.
src/app/layout.tsx - Global styles · Global visual system and base styling.
src/app/globals.css
Client UI
Chat experience and artifact presentation in the browser.
- Chat interface · Coordinates the user-facing assistant experience.
src/components/chat/ChatInterface.tsx - Input bar · Composes and submits user prompts.
src/components/chat/InputBar.tsx - Message view · Renders assistant and user messages in the thread.
src/components/chat/Message.tsx - Artifact panel · Displays interactive artifacts alongside text responses.
src/components/artifacts/ArtifactRenderer.tsx
Agent server
Chat API plus prompt, parsing, and tool orchestration.
- Chat API · Server endpoint that orchestrates the agent loop and streaming response.
src/app/api/chat/route.ts - System prompt · Controls tool use, artifact generation, and answer style.
src/agent/system-prompt.ts - Stream parser · Separates streamed text from embedded artifact markup.
src/agent/stream-parser.ts - Tool registry · Central export and registration point for agent tools.
src/agent/tools/index.ts - Duty cycle · Retrieves exact amperage and voltage duty-cycle tables.
src/agent/tools/duty-cycle.ts - Polarity lookup · Returns cable and socket polarity setup guidance.
src/agent/tools/polarity.ts - Settings recommender · Finds process, material, and thickness recommendations.
src/agent/tools/settings.ts - Troubleshooting · Traverses symptom, cause, and fix relationships.
src/agent/tools/troubleshooting.ts - Specs lookup · Retrieves machine specification data.
src/agent/tools/specs.ts - Manual images · Matches questions to relevant manual page images.
src/agent/tools/manual-images.ts
Knowledge assets
Committed domain data and extracted manual resources.
- Duty tables · Authoritative duty-cycle lookup data.
data/duty-cycle.json - Polarity data · Authoritative polarity and wiring data.
data/polarity.json - Settings data · Authoritative process and material recommendation data.
data/settings.json - Trouble graph · Structured symptom-to-cause-to-fix knowledge.
data/troubleshooting.json - Specs data · Authoritative machine specification data.
data/specs.json - Manual index · Keyword index for manual-page image retrieval.
data/manual-images.json - Manual pages · Extracted manual page images used for visual answers.
public/manual-images
Artifact runtime
Sandboxed browser runtime for interactive artifacts.
- Artifact runtime · Prebuilt iframe runtime for interactive artifact execution.
public/artifact-runtime.html
Connections 27
- 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.