# jijavemi/partspec architecture

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

- Interactive diagram: https://gitdiagram.com/jijavemi/partspec
- Repository: https://github.com/jijavemi/partspec

## Overview

PartSpec’s documented product spans an iOS app and a backend; this repository contains only the FastAPI backend, so the native UI and its local predefined-part lookup are not represented as code components here. The backend exposes health and search endpoints. A search request retrieves DuckDuckGo results (retrying with a specifications query when needed), asks Groq to produce structured part data, normalizes it into the PartSpec response model, and returns it. The source shows this backend flow; other README-described capabilities are not evidenced in the available files.

Main entry points: [`main.py`](https://github.com/jijavemi/partspec/blob/main/main.py) (Search endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_search["Search endpoint<br/>[main.py]"]
  node_health["Health endpoint<br/>[main.py]"]
end

subgraph group_retrieval["Web retrieval"]
  node_spec_lookup["Spec lookup<br/>[main.py]"]
  node_ddg_search["DuckDuckGo search<br/>[main.py]"]
  node_result_extract["Result extraction<br/>[main.py]"]
end

subgraph group_specs["Spec generation"]
  node_groq_generation["Groq generation<br/>[main.py]"]
  node_normalization["Response normalization<br/>[main.py]"]
  node_part_spec["PartSpec model<br/>[main.py]"]
end

node_engineer(("API caller"))
node_duckduckgo{{"DuckDuckGo"}}
node_groq{{"Groq API"}}

node_engineer -->|"queries"| node_search
node_engineer -->|"checks status"| node_health
node_search -->|"calls"| node_spec_lookup
node_spec_lookup -->|"searches; retries if sparse"| node_ddg_search
node_ddg_search -->|"requests results"| node_duckduckgo
node_ddg_search -->|"parses HTML"| node_result_extract
node_spec_lookup -->|"submits context"| node_groq_generation
node_groq_generation -->|"requests JSON"| node_groq
node_groq_generation -->|"parses response"| node_normalization
node_normalization -->|"constructs"| node_part_spec
node_search -->|"returns specs"| node_part_spec

click node_search "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_health "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_spec_lookup "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_ddg_search "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_result_extract "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_groq_generation "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_normalization "https://github.com/jijavemi/partspec/blob/main/main.py"
click node_part_spec "https://github.com/jijavemi/partspec/blob/main/main.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_search,node_health toneBlue
class node_spec_lookup,node_ddg_search,node_result_extract toneAmber
class node_groq_generation,node_normalization,node_part_spec,node_engineer,node_groq toneMint
class node_duckduckgo toneIndigo
```

## Components

### API

- [Search endpoint](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`
- [Health endpoint](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`

### Web retrieval

- [Spec lookup](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`
- [DuckDuckGo search](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`
- [Result extraction](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`

### Spec generation

- [Groq generation](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`
- [Response normalization](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`
- [PartSpec model](https://github.com/jijavemi/partspec/blob/main/main.py): `main.py`

### Other components

- **API caller**
- **DuckDuckGo**
- **Groq API**

## Connections

- API caller → Search endpoint: queries (evidence: `main.py`)
- API caller → Health endpoint: checks status (evidence: `main.py`)
- Search endpoint → Spec lookup: calls (evidence: `main.py`)
- Spec lookup → DuckDuckGo search: searches; retries if sparse (evidence: `main.py`)
- DuckDuckGo search → DuckDuckGo: requests results (evidence: `main.py`)
- DuckDuckGo search → Result extraction: parses HTML (evidence: `main.py`)
- Spec lookup → Groq generation: submits context (evidence: `main.py`)
- Groq generation → Groq API: requests JSON (evidence: `main.py`)
- Groq generation → Response normalization: parses response (evidence: `main.py`)
- Response normalization → PartSpec model: constructs (evidence: `main.py`)
- Search endpoint → PartSpec model: returns specs (evidence: `main.py`)
