# nickolasnolte1/factored-hackathon-2026-nico-x2.exe architecture

> Architecture diagram of the GitHub repository nickolasnolte1/factored-hackathon-2026-nico-x2.exe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe
- Repository: https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe

## Overview

This repository builds an AI-first banking dispute-service demo, backed by a staged Databricks data pipeline and controlled banking tools. A customer signs in, chats with the agent, and may receive a resolution or human handoff; the web app also exposes traces and an agent console. Other major branches generate evaluation scenarios, classify intake intent, and score agent outcomes. Edges use README statements or visible source-index references; unsampled implementation details and some runtime wiring are intentionally not inferred.

Main entry points: [`src/bank_tools/service.py`](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/service.py) (Bank tool service), [`app/server.py`](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/server.py) (Demo app server), [`app/agent.py`](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/agent.py) (Conversation agent), [`src/agent_eval/score.py`](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/agent_eval/score.py) (Outcome scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Customer experience"]
  node_web["Chat and console<br/>[app.js]"]
  node_server["Demo app server<br/>[server.py]"]
  node_agent["Conversation agent<br/>[agent.py]"]
  node_llm["Model client<br/>[llm.py]"]
end

subgraph group_banking["Banking controls"]
  node_tools["Bank tool service<br/>[service.py]"]
  node_repository[("Gold data repository")]
  node_audit[("Tool audit trail<br/>[audit.py]")]
  node_state[("Conversation state<br/>[state.py]")]
end

subgraph group_data["Data pipeline"]
  node_bronze["Bronze ingestion"]
  node_silver["Silver quality layer<br/>[silver_lib.py]"]
  node_gold[("Gold tables<br/>[gold_lib.py]")]
end

subgraph group_intelligence["AI and policy"]
  node_policy["Dispute policy<br/>[dispute_policy.py]"]
  node_classifier["Intent classifier<br/>[runtime.py]"]
end

subgraph group_evaluation["Scenario evaluation"]
  node_scenario["Scenario generation<br/>[generate.py]"]
  node_eval["Agent evaluation<br/>[run.py]"]
  node_scoring["Outcome scoring<br/>[score.py]"]
end

node_customer(("Customer"))
node_databricks{{"Databricks"}}

node_customer -->|"uses"| node_web
node_web -.->|"sends requests"| node_server
node_server -->|"routes chat"| node_agent
node_server -->|"uses sign-in tools"| node_tools
node_server -->|"uses classifier"| node_classifier
node_agent -->|"calls"| node_llm
node_agent -->|"calls tools"| node_tools
node_llm -->|"requests model"| node_databricks
node_tools -->|"reads and writes"| node_repository
node_tools -.->|"records calls"| node_audit
node_tools -->|"uses state"| node_state
node_tools -->|"applies rules"| node_policy
node_repository -->|"reads snapshot"| node_gold
node_bronze -->|"feeds"| node_silver
node_silver -->|"builds from"| node_gold
node_gold -->|"built on"| node_databricks
node_scenario -->|"computes expected outcomes"| node_policy
node_scenario -.->|"uses anchors"| node_silver
node_eval -->|"runs agent"| node_agent
node_eval -->|"scores runs"| node_scoring
node_scoring -->|"checks policy outcomes"| node_policy
node_scoring -->|"looks up snapshot"| node_repository

click node_web "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/static/app.js"
click node_server "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/server.py"
click node_agent "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/agent.py"
click node_llm "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/llm.py"
click node_tools "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/service.py"
click node_repository "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/tree/main/src/bank_tools/repository"
click node_audit "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/audit.py"
click node_state "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/state.py"
click node_policy "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/policy/dispute_policy.py"
click node_classifier "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/classifier/runtime.py"
click node_bronze "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/tree/main/src/bronze"
click node_silver "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/silver/silver_lib.py"
click node_gold "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/gold/gold_lib.py"
click node_scenario "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/scenarios/generate.py"
click node_eval "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/agent_eval/run.py"
click node_scoring "https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/agent_eval/score.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_web,node_server,node_agent,node_llm toneBlue
class node_tools,node_repository,node_audit,node_state toneAmber
class node_bronze,node_silver,node_gold toneMint
class node_policy,node_classifier toneRose
class node_scenario,node_eval,node_scoring,node_customer,node_databricks toneIndigo
```

## Components

### Customer experience

- [Chat and console](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/static/app.js): `app/static/app.js`
- [Demo app server](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/server.py): `app/server.py`
- [Conversation agent](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/agent.py): `app/agent.py`
- [Model client](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/app/llm.py): `app/llm.py`

### Banking controls

- [Bank tool service](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/service.py): `src/bank_tools/service.py`
- [Gold data repository](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/tree/main/src/bank_tools/repository): `src/bank_tools/repository`
- [Tool audit trail](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/audit.py): `src/bank_tools/audit.py`
- [Conversation state](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/bank_tools/state.py): `src/bank_tools/state.py`

### Data pipeline

- [Bronze ingestion](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/tree/main/src/bronze): `src/bronze`
- [Silver quality layer](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/silver/silver_lib.py): `src/silver/silver_lib.py`
- [Gold tables](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/gold/gold_lib.py): `src/gold/gold_lib.py`

### AI and policy

- [Dispute policy](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/policy/dispute_policy.py): `src/policy/dispute_policy.py`
- [Intent classifier](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/classifier/runtime.py): `src/classifier/runtime.py`

### Scenario evaluation

- [Scenario generation](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/scenarios/generate.py): `src/scenarios/generate.py`
- [Agent evaluation](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/agent_eval/run.py): `src/agent_eval/run.py`
- [Outcome scoring](https://github.com/nickolasnolte1/factored-hackathon-2026-nico-x2.exe/blob/main/src/agent_eval/score.py): `src/agent_eval/score.py`

### Other components

- **Customer**
- **Databricks**

## Connections

- Customer → Chat and console: uses (evidence: `README.md`)
- Chat and console → Demo app server: sends requests
- Demo app server → Conversation agent: routes chat (evidence: `app/server.py`)
- Demo app server → Bank tool service: uses sign-in tools (evidence: `app/server.py`)
- Demo app server → Intent classifier: uses classifier (evidence: `app/server.py`)
- Conversation agent → Model client: calls (evidence: `app/agent.py`)
- Conversation agent → Bank tool service: calls tools (evidence: `app/agent.py`)
- Model client → Databricks: requests model (evidence: `README.md`)
- Bank tool service → Gold data repository: reads and writes (evidence: `src/bank_tools/service.py`)
- Bank tool service → Tool audit trail: records calls
- Bank tool service → Conversation state: uses state (evidence: `src/bank_tools/service.py`)
- Bank tool service → Dispute policy: applies rules (evidence: `src/bank_tools/service.py`)
- Gold data repository → Gold tables: reads snapshot (evidence: `README.md`)
- Bronze ingestion → Silver quality layer: feeds (evidence: `README.md`)
- Silver quality layer → Gold tables: builds from (evidence: `src/gold/01_build_gold.py`)
- Gold tables → Databricks: built on (evidence: `README.md`)
- Scenario generation → Dispute policy: computes expected outcomes (evidence: `src/scenarios/generate.py`)
- Scenario generation → Silver quality layer: uses anchors
- Agent evaluation → Conversation agent: runs agent (evidence: `README.md`)
- Agent evaluation → Outcome scoring: scores runs (evidence: `README.md`)
- Outcome scoring → Dispute policy: checks policy outcomes (evidence: `src/agent_eval/score.py`)
- Outcome scoring → Gold data repository: looks up snapshot (evidence: `src/agent_eval/score.py`)