# wangzihe0326/matfinder-ai architecture

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

- Interactive diagram: https://gitdiagram.com/wangzihe0326/matfinder-ai
- Repository: https://github.com/wangzihe0326/matfinder-ai

## Overview

MatFinder AI takes a user’s material requirements through local catalog search and evidence-aware recommendation, then supports material details, comparisons, optional AI explanations, and report export. The browser app is the user-facing orchestrator; the Node server owns API requests, repository reads, and optional OpenAI calls. SQLite is the documented source of truth. README capabilities inform the page, comparison, and export nodes; sampled excerpts do not establish every UI-to-module call or all evidence-validation wiring, so uncertain links are omitted.

Main entry points: [`public/app.js`](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js) (Multi-page app), [`server.js`](https://github.com/wangzihe0326/matfinder-ai/blob/main/server.js) (HTTP API server), [`material-repository.js`](https://github.com/wangzihe0326/matfinder-ai/blob/main/material-repository.js) (Material repository), [`evidence-model.js`](https://github.com/wangzihe0326/matfinder-ai/blob/main/evidence-model.js) (Evidence model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_app["Multi-page app<br/>[app.js]"]
  node_catalog["Material catalog<br/>[catalog-layer.js]"]
  node_family["Polymer families"]
  node_detail["Material detail<br/>[app.js]"]
  node_compare["Compare workflow<br/>[app.js]"]
  node_analysis["AI explanations<br/>[app.js]"]
  node_report["Selection report<br/>[app.js]"]
end

subgraph group_matching["Catalog and matching"]
  node_search["Catalog search<br/>[catalog-search.js]"]
  node_recommend["Recommendation engine"]
  node_materials["Curated material source<br/>[materials.js]"]
end

subgraph group_backend["API and services"]
  node_server["HTTP API server<br/>[server.js]"]
  node_repo["Material repository"]
  node_sqlite[("SQLite catalog")]
  node_protection["API protection<br/>[api-protection.js]"]
end

subgraph group_evidence["Evidence and quality"]
  node_evidence["Evidence model<br/>[evidence-model.js]"]
  node_validator["Evidence validation"]
  node_quality["Material quality"]
end

node_user(("Material selector"))
node_openai["OpenAI API"]

node_user -->|"enters requirements"| node_app
node_app -->|"searches catalog"| node_search
node_app -->|"ranks requirements"| node_recommend
node_app -->|"browses catalog"| node_catalog
node_app -->|"searches families"| node_family
node_app -->|"requests materials"| node_server
node_server -->|"queries records"| node_repo
node_repo -->|"reads catalog"| node_sqlite
node_materials -.->|"source of truth"| node_sqlite
node_app -->|"opens selection"| node_detail
node_app -->|"selects materials"| node_compare
node_app -->|"requests explanation"| node_analysis
node_analysis -->|"posts analysis"| node_server
node_server -->|"loads profiles"| node_repo
node_server -.->|"requests narrative"| node_openai
node_app -->|"posts comparison"| node_server
node_server -.->|"requests comparison"| node_openai
node_server -->|"checks access"| node_protection
node_app -->|"exports report"| node_report
node_repo -->|"normalizes evidence"| node_evidence
node_quality -->|"uses definitions"| node_evidence

click node_app "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js"
click node_catalog "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/catalog-layer.js"
click node_family "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/polymer-families.js"
click node_search "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/catalog-search.js"
click node_recommend "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/recommendation-engine.js"
click node_materials "https://github.com/wangzihe0326/matfinder-ai/blob/main/data/materials.js"
click node_server "https://github.com/wangzihe0326/matfinder-ai/blob/main/server.js"
click node_repo "https://github.com/wangzihe0326/matfinder-ai/blob/main/material-repository.js"
click node_protection "https://github.com/wangzihe0326/matfinder-ai/blob/main/api-protection.js"
click node_evidence "https://github.com/wangzihe0326/matfinder-ai/blob/main/evidence-model.js"
click node_validator "https://github.com/wangzihe0326/matfinder-ai/blob/main/evidence-validator.js"
click node_quality "https://github.com/wangzihe0326/matfinder-ai/blob/main/material-quality.js"
click node_detail "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js"
click node_compare "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js"
click node_analysis "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js"
click node_report "https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js"

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_app,node_catalog,node_family,node_detail,node_compare,node_analysis,node_report toneBlue
class node_search,node_recommend,node_materials toneAmber
class node_server,node_repo,node_sqlite,node_protection,node_openai toneMint
class node_evidence,node_validator,node_quality toneRose
class node_user toneIndigo
```

## Components

### Browser experience

- [Multi-page app](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js): `public/app.js`
- [Material catalog](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/catalog-layer.js): `public/catalog-layer.js`
- [Polymer families](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/polymer-families.js): `public/polymer-families.js`
- [Material detail](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js): `public/app.js`
- [Compare workflow](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js): `public/app.js`
- [AI explanations](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js): `public/app.js`
- [Selection report](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/app.js): `public/app.js`

### Catalog and matching

- [Catalog search](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/catalog-search.js): `public/catalog-search.js`
- [Recommendation engine](https://github.com/wangzihe0326/matfinder-ai/blob/main/public/recommendation-engine.js): `public/recommendation-engine.js`
- [Curated material source](https://github.com/wangzihe0326/matfinder-ai/blob/main/data/materials.js): `data/materials.js`

### API and services

- [HTTP API server](https://github.com/wangzihe0326/matfinder-ai/blob/main/server.js): `server.js`
- [Material repository](https://github.com/wangzihe0326/matfinder-ai/blob/main/material-repository.js): `material-repository.js`
- **SQLite catalog**
- [API protection](https://github.com/wangzihe0326/matfinder-ai/blob/main/api-protection.js): `api-protection.js`

### Evidence and quality

- [Evidence model](https://github.com/wangzihe0326/matfinder-ai/blob/main/evidence-model.js): `evidence-model.js`
- [Evidence validation](https://github.com/wangzihe0326/matfinder-ai/blob/main/evidence-validator.js): `evidence-validator.js`
- [Material quality](https://github.com/wangzihe0326/matfinder-ai/blob/main/material-quality.js): `material-quality.js`

### Other components

- **Material selector**
- **OpenAI API**

## Connections

- Material selector → Multi-page app: enters requirements
- Multi-page app → Catalog search: searches catalog
- Multi-page app → Recommendation engine: ranks requirements
- Multi-page app → Material catalog: browses catalog
- Multi-page app → Polymer families: searches families
- Multi-page app → HTTP API server: requests materials
- HTTP API server → Material repository: queries records
- Material repository → SQLite catalog: reads catalog
- Curated material source → SQLite catalog: source of truth
- Multi-page app → Material detail: opens selection
- Multi-page app → Compare workflow: selects materials
- Multi-page app → AI explanations: requests explanation
- AI explanations → HTTP API server: posts analysis
- HTTP API server → Material repository: loads profiles
- HTTP API server → OpenAI API: requests narrative
- Multi-page app → HTTP API server: posts comparison
- HTTP API server → OpenAI API: requests comparison
- HTTP API server → API protection: checks access
- Multi-page app → Selection report: exports report
- Material repository → Evidence model: normalizes evidence
- Material quality → Evidence model: uses definitions