# yashumani/drill-down-anamoly architecture

> Architecture diagram of the GitHub repository yashumani/drill-down-anamoly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yashumani/drill-down-anamoly
- Repository: https://github.com/yashumani/drill-down-anamoly

## Overview

#### Purpose and runtime

Drill-down Anomaly Lab is a client-side React/TypeScript research prototype for investigating tabular-data anomalies across all eligible dimensions rather than following a predefined drill hierarchy. The browser app accepts CSV/JSON or deterministic demo data, derives anomaly drivers and interactions, and renders an investigation tree.

Entry points are `src/main.tsx` (React bootstrap) and `src/App.tsx` (application state and orchestration). Static deployment artifacts are published through `.github/workflows/pages.yml`.

#### Data ingestion and schema boundary

`src/lib/io.ts` parses CSV and JSON into tabular row objects. `src/data/sampleData.ts` supplies the built-in synthetic dataset for validation and demonstration.

`src/lib/profile.ts` profiles columns and classifies numeric measures, categorical dimensions, dates, booleans, and identifier-like/high-cardinality fields. This inferred schema is the boundary between arbitrary input data and the analytical engine; only eligible dimensions and selected numeric measures enter scoring.

Shared row, profile, investigation, and visualization contracts are centralized in `src/types.ts`.

#### Investigation state and cohort control

`src/App.tsx` owns the selected Actual measure, optional Expected/Target measure, dataset/profile state, and the active drill path. Each drill selection is treated as an added cohort filter, not as navigation within a static dimension tree.

A new cohort triggers a full re-analysis of the filtered rows. The resulting path records investigation history and allows the UI to compare the current population with selected segment populations.

#### Anomaly analysis engine

`src/lib/anomaly.ts` is the core analytical stage. For each cohort it computes row residuals (`actual - expected`, or a cohort-mean baseline), independently groups all eligible dimensions, and ranks dimensions using interpretable impact, surprise, variance concentration, and support signals.

It then ranks category values by variance contribution and searches pruned two- and three-way interactions among leading dimensions/categories. This is intentionally browser-scale computation; enterprise-scale group-bys, scoring, interaction search, authorization, and row evidence should move behind the same UI-facing contract.

#### Chat and analytical assistance

`src/lib/chatEngine.ts` provides the local chat/investigation assistant behavior used by `src/components/ChatPanel.tsx`. It operates on the app’s current analytical context rather than representing a documented external AI service integration.

The chat panel is therefore a presentation/control surface over client-side investigation state, alongside visual drill actions.

#### Visualization and user interaction

`src/components/Visuals.tsx` renders the investigation tree, all-dimension driver landscape, category contributions, interaction segments, KPI summaries, and audit-oriented views. Selecting a category or interaction feeds a new cohort filter back to `src/App.tsx`.

`src/components/EChart.tsx` is the reusable chart adapter, isolating chart-library lifecycle concerns from analytical and state-management logic. `src/styles.css` provides the application styling layer.

#### Deployment and documentation

The app is a static frontend built with the npm scripts in `package.json`; no server, database, or external API is represented in the repository. GitHub Pages deployment is configured at `.github/workflows/pages.yml`.

Research rationale and implementation-oriented architecture notes live in `docs/all-dimension-investigation-tree.md` and `docs/prototype-architecture.md`; the generated/static site surface is under `docs/` and `index.html`.

Main entry points: [`src/App.tsx`](https://github.com/yashumani/drill-down-anamoly/blob/main/src/App.tsx) (App orchestration), [`src/components/Visuals.tsx`](https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/Visuals.tsx) (Investigation views), [`src/types.ts`](https://github.com/yashumani/drill-down-anamoly/blob/main/src/types.ts) (Shared contracts), [`src/components/ChatPanel.tsx`](https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/ChatPanel.tsx) (Chat panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_bootstrap(("React bootstrap<br/>entry point<br/>[main.tsx]"))
  node_app["App orchestration<br/>application state<br/>[App.tsx]"]
  node_visuals["Investigation views<br/>React views<br/>[Visuals.tsx]"]
  node_chart["Chart adapter<br/>chart lifecycle adapter<br/>[EChart.tsx]"]
  node_chat_panel["Chat panel<br/>React control surface<br/>[ChatPanel.tsx]"]
  node_styles["Application styles<br/>styling<br/>[styles.css]"]
end

subgraph group_analysis["Analysis Pipeline"]
  node_io["CSV/JSON parser<br/>ingestion boundary<br/>[io.ts]"]
  node_profile["Schema profiler<br/>schema inference<br/>[profile.ts]"]
  node_anomaly{{"Anomaly engine<br/>cohort analysis<br/>[anomaly.ts]"}}
  node_chat_engine["Local investigation assistant<br/>contextual chat logic<br/>[chatEngine.ts]"]
  node_contracts["Shared contracts<br/>TypeScript types<br/>[types.ts]"]
end

subgraph group_data["Data Sources"]
  node_uploads["CSV/JSON input<br/>user-provided data"]
  node_sample_data["Synthetic demo data<br/>built-in dataset<br/>[sampleData.ts]"]
end

subgraph group_delivery["Delivery &amp; Docs"]
  node_pages["GitHub Pages deploy<br/>deployment workflow<br/>[pages.yml]"]
  node_static_site["Static site surface<br/>published frontend<br/>[index.html]"]
  node_research_docs["Research rationale<br/>architecture documentation"]
  node_prototype_docs["Prototype architecture notes<br/>architecture documentation"]
end

node_bootstrap -->|"mounts"| node_app
node_uploads -->|"parse"| node_io
node_sample_data -->|"demo rows"| node_app
node_io -->|"tabular rows"| node_profile
node_profile -->|"inferred schema"| node_app
node_app -->|"filtered cohort and measures"| node_anomaly
node_anomaly -->|"ranked investigation"| node_app
node_app -->|"state and results"| node_visuals
node_visuals -->|"category/interaction drill"| node_app
node_visuals -->|"render charts"| node_chart
node_app -->|"analytical context"| node_chat_panel
node_chat_panel -->|"assistant request"| node_chat_engine
node_chat_engine -->|"local response"| node_chat_panel
node_contracts -.->|"shared types"| node_app
node_contracts -.->|"shared types"| node_anomaly
node_contracts -.->|"shared types"| node_visuals
node_styles -.->|"styles"| node_app
node_static_site -->|"published by"| node_pages
node_pages -->|"deploys"| node_static_site
node_research_docs -.->|"complements"| node_prototype_docs

click node_bootstrap "https://github.com/yashumani/drill-down-anamoly/blob/main/src/main.tsx"
click node_app "https://github.com/yashumani/drill-down-anamoly/blob/main/src/App.tsx"
click node_visuals "https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/Visuals.tsx"
click node_chart "https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/EChart.tsx"
click node_chat_panel "https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/ChatPanel.tsx"
click node_styles "https://github.com/yashumani/drill-down-anamoly/blob/main/src/styles.css"
click node_io "https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/io.ts"
click node_profile "https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/profile.ts"
click node_anomaly "https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/anomaly.ts"
click node_chat_engine "https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/chatEngine.ts"
click node_contracts "https://github.com/yashumani/drill-down-anamoly/blob/main/src/types.ts"
click node_sample_data "https://github.com/yashumani/drill-down-anamoly/blob/main/src/data/sampleData.ts"
click node_pages "https://github.com/yashumani/drill-down-anamoly/blob/main/.github/workflows/pages.yml"
click node_static_site "https://github.com/yashumani/drill-down-anamoly/blob/main/index.html"
click node_research_docs "https://github.com/yashumani/drill-down-anamoly/blob/main/docs/all-dimension-investigation-tree.md"
click node_prototype_docs "https://github.com/yashumani/drill-down-anamoly/blob/main/docs/prototype-architecture.md"

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_bootstrap,node_app,node_visuals,node_chart,node_chat_panel,node_styles toneBlue
class node_io,node_profile,node_anomaly,node_chat_engine,node_contracts toneAmber
class node_uploads,node_sample_data toneMint
class node_pages,node_static_site,node_research_docs,node_prototype_docs toneRose
```

## Components

### Browser UI

- [React bootstrap](https://github.com/yashumani/drill-down-anamoly/blob/main/src/main.tsx): entry point · `src/main.tsx`
- [App orchestration](https://github.com/yashumani/drill-down-anamoly/blob/main/src/App.tsx): application state · Owns measures, schema, cohort, and drill path. · `src/App.tsx`
- [Investigation views](https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/Visuals.tsx): React views · Tree, drivers, contributions, interactions, KPIs, and audit views. · `src/components/Visuals.tsx`
- [Chart adapter](https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/EChart.tsx): chart lifecycle adapter · `src/components/EChart.tsx`
- [Chat panel](https://github.com/yashumani/drill-down-anamoly/blob/main/src/components/ChatPanel.tsx): React control surface · `src/components/ChatPanel.tsx`
- [Application styles](https://github.com/yashumani/drill-down-anamoly/blob/main/src/styles.css): styling · `src/styles.css`

### Analysis Pipeline

- [CSV/JSON parser](https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/io.ts): ingestion boundary · Converts uploaded files into tabular rows. · `src/lib/io.ts`
- [Schema profiler](https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/profile.ts): schema inference · Classifies measures, dimensions, dates, booleans, and identifiers. · `src/lib/profile.ts`
- [Anomaly engine](https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/anomaly.ts): cohort analysis · Scores drivers, category contributions, and pruned interactions. · `src/lib/anomaly.ts`
- [Local investigation assistant](https://github.com/yashumani/drill-down-anamoly/blob/main/src/lib/chatEngine.ts): contextual chat logic · Uses the current client-side analytical context. · `src/lib/chatEngine.ts`
- [Shared contracts](https://github.com/yashumani/drill-down-anamoly/blob/main/src/types.ts): TypeScript types · Rows, profiles, investigations, and visualization contracts. · `src/types.ts`

### Data Sources

- **CSV/JSON input**: user-provided data
- [Synthetic demo data](https://github.com/yashumani/drill-down-anamoly/blob/main/src/data/sampleData.ts): built-in dataset · `src/data/sampleData.ts`

### Delivery & Docs

- [GitHub Pages deploy](https://github.com/yashumani/drill-down-anamoly/blob/main/.github/workflows/pages.yml): deployment workflow · `.github/workflows/pages.yml`
- [Static site surface](https://github.com/yashumani/drill-down-anamoly/blob/main/index.html): published frontend · `index.html`
- [Research rationale](https://github.com/yashumani/drill-down-anamoly/blob/main/docs/all-dimension-investigation-tree.md): architecture documentation · `docs/all-dimension-investigation-tree.md`
- [Prototype architecture notes](https://github.com/yashumani/drill-down-anamoly/blob/main/docs/prototype-architecture.md): architecture documentation · `docs/prototype-architecture.md`

## Connections

- React bootstrap → App orchestration: mounts
- CSV/JSON input → CSV/JSON parser: parse
- Synthetic demo data → App orchestration: demo rows
- CSV/JSON parser → Schema profiler: tabular rows
- Schema profiler → App orchestration: inferred schema
- App orchestration → Anomaly engine: filtered cohort and measures
- Anomaly engine → App orchestration: ranked investigation
- App orchestration → Investigation views: state and results
- Investigation views → App orchestration: category/interaction drill · Adds a cohort filter and triggers re-analysis.
- Investigation views → Chart adapter: render charts
- App orchestration → Chat panel: analytical context
- Chat panel → Local investigation assistant: assistant request
- Local investigation assistant → Chat panel: local response
- Shared contracts → App orchestration: shared types
- Shared contracts → Anomaly engine: shared types
- Shared contracts → Investigation views: shared types
- Application styles → App orchestration: styles
- Static site surface → GitHub Pages deploy: published by
- GitHub Pages deploy → Static site surface: deploys
- Research rationale → Prototype architecture notes: complements