# chipdocs.org — Full Technical Specification & LLM Reference Manual (llms-full.txt)

> chipdocs.org is an open-source, AI-powered interactive 2D/3D electronic component portal, parametric CAD engine, and automated datasheet extraction platform. This document is the comprehensive, self-contained reference manual designed for AI coding agents, autonomous LLM pipelines, and hardware engineering tools.

---

## Table of Contents
1. [Architecture & Philosophy](#1-architecture--philosophy)
2. [Component Catalog & Manufacturer Taxonomy](#2-component-catalog--manufacturer-taxonomy)
3. [Component Master Schema (JSON Specification)](#3-component-master-schema-json-specification)
4. [IPC-7351B Mathematical Normalizer & Rules](#4-ipc-7351b-mathematical-normalizer--rules)
5. [3D CAD Synthesis Engine (build123d & AP214)](#5-3d-cad-synthesis-engine-build123d--ap214)
6. [EDA Multi-Format Library Compilation](#6-eda-multi-format-library-compilation)
7. [REST API Complete Specification](#7-rest-api-complete-specification)
8. [Concrete Examples for AI Agents](#8-concrete-examples-for-ai-agents)
9. [Open Source Licensing & Compliance](#9-open-source-licensing--compliance)

---

## 1. Architecture & Philosophy

The chipdocs.org platform solves the critical bottleneck in electronics design: turning unstandardized, rasterized PDF datasheets from hundreds of semiconductor vendors into clean, verified, machine-actionable ECAD/MCAD assets.

### The Clean-Room Guarantee
- **Zero Hallucination Grounding**: Every dimension (body size, lead pitch, pad width), pin assignment, and operating limit is linked to an exact page number and bounding box citation in the manufacturer's original PDF datasheet.
- **IPC-7351B Determinism**: Footprint pads are synthesized mathematically from nominal mechanical lead spans using IPC-7351B formulas rather than copied from unverified vendor drawings.
- **3-Way Synchronization**: In the web UI, the 3D WebGL model, 2D IPC-7351B canvas overlay, and IEEE-315 schematic pinout table are linked in real-time via Zustand state. Clicking Pin 1 in 3D highlights Pin 1 in 2D and jumps to Pin 1 in the pinout table.

---

## 2. Component Catalog & Manufacturer Taxonomy

chipdocs.org indexes over 2,300 components across 64 registered semiconductor manufacturers.

### Top Manufacturers Breakdown
| Manufacturer Identifier | Typical Families | Component Count |
| :--- | :--- | :--- |
| **ST / STMicroelectronics** | STM32 (F0/F1/F4/L4/G4/H7), STM8, L78xx, LD3985, VIPer, USBLC6 | ~1,450+ |
| **WCH (Nanjing Qinheng)** | CH32V003, CH32V203, CH340G/C/E/N, CH552, CH9329, CH347 | 250+ |
| **ESPRESSIF (Espressif Systems)** | ESP32-S3, ESP32-C3, ESP32-C6, ESP32-S2, ESP8266, ESP32-WROOM | 260+ |
| **Kiwi Instruments** | KP101, KP201, KP3110, KP1051, KP1071 (AC-DC & LED drivers) | 168+ |
| **MICROCHIP (Microchip Technology)** | PIC16F, PIC18F, ATmega328P, ATtiny85, 24LCxx EEPROMs, DSC oscillators | 82+ |
| **TI (Texas Instruments)** | TLV62568, TPS61040, CD4051, NE555, LM358 | 12+ |
| **GigaDevice Semicon** | GD32F103, GD32E230, GD25Q32 | 4+ |
| **ADI (Analog Devices)** | ADM2483, AD8605, AD8226 | 5+ |
| **Lattice Semiconductor** | iCE40UP5K, LCMXO2 | 4+ |
| **HGSEMI** | LM358, NE555, 74HC595, AMS1117 | 3+ |

### Supported Package Taxonomies
- **QFN / DFN**: Quad / Dual Flat No-Lead (e.g. QFN-16, QFN-32, QFN-48, QFN-56, DFN-8).
- **LQFP / TQFP**: Low-profile / Thin Quad Flat Package (e.g. LQFP-48, LQFP-64, LQFP-100, LQFP-144).
- **SOIC / SOP / TSSOP**: Small Outline Integrated Circuit (e.g. SOIC-8, SOIC-16, TSSOP-20).
- **BGA**: Ball Grid Array (e.g. BGA-64, BGA-100, WLCSP).
- **SOT / SOD**: Small Outline Transistor / Diode (e.g. SOT-23, SOT-223, SOT-89, SOD-123).
- **Castellated Modules**: RF & SoC stamp-hole modules (e.g. ESP32-WROOM-32, ESP32-S3-WROOM-1, SMD-41P).

---

## 3. Component Master Schema (JSON Specification)

All component extractions adhere to the following master schema definition (implemented via Pydantic in `app.models.pydantic_schemas`):

```json
{
  "lcsc_part": "string (e.g. 'C6553339')",
  "mpn": "string (e.g. 'ESP32-S2-SOLO-2U-N4R2')",
  "manufacturer": "string (e.g. 'ESPRESSIF')",
  "package": "string (e.g. 'SMD-41P')",
  "description": "string",
  "routing": {
    "total_pages": "integer",
    "cover_pages": ["integer"],
    "pinout_pages": ["integer"],
    "mechanical_pages": ["integer"],
    "footprint_pages": ["integer"],
    "electrical_pages": ["integer"],
    "toc_entries": [
      { "level": "integer", "title": "string", "page": "integer" }
    ]
  },
  "mechanical_dimensions": {
    "package_code": "string",
    "lead_count": "integer",
    "pin1_location": "TOP_LEFT | BOTTOM_LEFT | CHAMFER | DOT",
    "body_length_D": { "min": "float", "nom": "float", "max": "float" },
    "body_width_E": { "min": "float", "nom": "float", "max": "float" },
    "overall_height_A": { "min": "float", "nom": "float", "max": "float" },
    "pitch_e": "float (lead pitch in millimeters)",
    "lead_width_b": { "min": "float", "nom": "float", "max": "float" },
    "lead_length_L": { "min": "float", "nom": "float", "max": "float" },
    "span_D1": { "min": "float", "nom": "float", "max": "float" },
    "span_E1": { "min": "float", "nom": "float", "max": "float" }
  },
  "recommended_land_pattern": {
    "pitch_mm": "float",
    "pad_width_X": "float (copper pad width in mm)",
    "pad_length_Y": "float (copper pad length in mm)",
    "center_pad_width": "float | null (EPAD thermal width in mm)",
    "center_pad_length": "float | null (EPAD thermal length in mm)",
    "span_Cx": "float (center-to-center pad row span in mm)",
    "span_Cy": "float (center-to-center pad col span in mm)",
    "synthesized_pads": [
      {
        "pad_number": "string | integer (e.g. '1', 'EPAD')",
        "x_mm": "float (center X coordinate relative to chip origin (0,0))",
        "y_mm": "float (center Y coordinate relative to chip origin (0,0))",
        "width_mm": "float",
        "height_mm": "float",
        "shape": "RECTANGLE | ROUNDED_RECT | CIRCLE",
        "layer": "TOP_COPPER"
      }
    ]
  },
  "pins": [
    {
      "pin_number": "string | integer (e.g. '1')",
      "pin_name": "string (e.g. 'IO0', 'VDD33', 'GND')",
      "electrical_type": "POWER | GROUND | INPUT | OUTPUT | BIDIRECTIONAL | OPEN_DRAIN | PASSIVE | ANALOG | NC",
      "pin_group": "string (e.g. 'POWER', 'GPIO', 'SPI', 'UART')",
      "primary_function": "string",
      "alternate_functions": ["string"],
      "i18n": {
        "vi": { "title": "string", "description": "string" },
        "en": { "title": "string", "description": "string" }
      }
    }
  ],
  "electrical_summary": {
    "supply_voltage_range": "string (e.g. '3.0 ~ 3.6 V')",
    "operating_temperature_range": "string (e.g. '-40 ~ 105 °C')",
    "max_current": "string",
    "absolute_maximum_ratings": {
      "vcc_max_volts": "float",
      "storage_temp_max_c": "float"
    }
  },
  "cleanroom_cad": {
    "kicad_footprint_sha256": "string",
    "fusion360_lbr_sha256": "string",
    "step_3d_sha256": "string",
    "glb_3d_sha256": "string",
    "license": "CERN-OHL-P-2.0"
  }
}
```

---

## 4. IPC-7351B Mathematical Normalizer & Rules

To eliminate solder bridge risks and floating pins, chipdocs.org utilizes strict IPC-7351B (Density Level B — Nominal) mathematical normalization:

### 1. Dimension Span Normalization (C / G / Z)
Different datasheets express land patterns using varying dimension conventions:
- **Outer Span ($Z$)**: Distance between outer edges of opposing pads.
- **Inner Span ($G$)**: Distance between inner edges of opposing pads (clearance).
- **Center-to-Center Span ($C$)**: Distance between centerlines of opposing pads.

The normalizer converts all formats to canonical center-to-center span $C$ via:
$$C = \frac{Z_{max} + G_{min}}{2}$$
$$X = Z_{max} - C = C - G_{min}$$

Where:
- $Z_{max} = D_{min} + 2 J_T + \sqrt{C_D^2 + C_T^2}$
- $G_{min} = D_{max} - 2 J_H - \sqrt{C_D^2 + C_H^2}$
- $J_T, J_H, J_S$ are toe, heel, and side solder fillet goals specified by IPC-7351B.

### 2. Overlap Interception
If $pad\_width \ge pitch$, the mathematical normalizer intercepts the anomaly and scales pad widths to enforce a minimum solder mask clearance of $0.15\text{ mm}$.

### 3. Solder Paste Grid Segmentation (IPC-7525)
For large exposed thermal pads (EPAD / Center Pad):
- Solder paste coverage must not exceed 50% to 65% of the total thermal pad area to avoid gas entrapment and component floating during reflow soldering.
- chipdocs.org divides the EPAD into a segmented $M \times N$ matrix (typically $2 \times 2$ or $3 \times 3$) of paste apertures with $0.20\text{ mm}$ minimum stencil web bridges, targeting exactly 60% solder paste coverage according to IPC-7525.

---

## 5. 3D CAD Synthesis Engine (build123d & AP214)

3D models are synthesized programmatically using the Python `build123d` kernel:

- **STEP AP214 Standard**: Includes application protocol colors:
  - Epoxy Resin Molding Body: Dark Charcoal Grey (`#1A1A1A` / RGB `0.10, 0.10, 0.10`)
  - Terminations & Gull-wing Leads: Matte Tin / Silver (`#E0E0E0` / RGB `0.88, 0.88, 0.88`)
  - Exposed Copper Thermal Pad: Metallic Copper (`#B87333` / RGB `0.72, 0.45, 0.20`)
  - Gold Plating / Castellated Pads: ENIG Gold (`#D4AF37` / RGB `0.83, 0.69, 0.22`)
  - Pin 1 Polarity Indicator: Debossed Dot or Laser-Etched Chamfer
- **Interactive WebGL GLB Models**:
  - Exported with a named hierarchy of mesh nodes: `PIN_1`, `PIN_2`, ..., `PIN_N`, `BODY`, `EPAD`.
  - Enables Three.js / React Three Fiber raycasters to detect hover and selection on individual pins.

---

## 6. EDA Multi-Format Library Compilation

A single verified component specification compiles to the following industry EDA formats:

1. **KiCad 8 (`.kicad_mod`, `.kicad_sym`)**:
   - Modern S-expression format (`(footprint ...)` and `(kicad_symbol ...)`).
   - Generates exact F.Cu (Copper), F.Mask (Solder Mask with $0.05\text{ mm}$ expansion), F.Paste (Solder Paste Stencil), F.Silkscreen (silkscreen reference and pin 1 indicator), and F.Courtyard ($0.25\text{ mm}$ boundary).
2. **Autodesk Fusion 360 & EAGLE (`.lbr`)**:
   - XML eagle.dtd 9.6.2 compliant component library containing `<package3d>`, `<package>`, `<symbols>`, and `<deviceset>` definitions.
3. **Altium Designer**:
   - Script-compatible geometric primitives and STEP model linking.

---

## 7. REST API Complete Specification

### `GET /api/v1/components`
Query catalog items.
- **Query Parameters**:
  - `q` (string): Keyword or part number filter.
  - `mfg` (string): Exact manufacturer filter (e.g. `ST`, `ESPRESSIF`, `WCH`).
  - `pkg` (string): Package style (e.g. `QFN`, `BGA`, `LQFP`, `SOIC`, `MODULE`).
  - `page` (int, default: 1): Page number.
  - `limit` (int, default: 20, max: 100): Items per page.
- **Example**: `GET /api/v1/components?q=STM32F4&pkg=LQFP`

### `GET /api/v1/components/{part_id}`
Retrieve full technical report.
- **Parameters**: `part_id` = LCSC part code (e.g. `C8734`), MPN, or SEO slug.
- **Response**: Full JSON `DatasheetExtractionReport` with routing, mechanical dimensions, land pattern coordinates, pinout, electrical summary, and asset URLs.

### `GET /api/v1/components/{part_id}/markdown`
Retrieve dense, token-efficient Markdown summary for AI agents.
- **Alternative**: Request `GET /api/v1/components/{part_id}` with header `Accept: text/markdown` or append `?format=markdown`.

### `GET /api/v1/assets/{part_id}/{filename}`
Direct static download for CAD models, vector diagrams, and PDFs.
- `cleanroom/kicad.zip`: KiCad 8 footprint and symbol.
- `cleanroom/fusion360.lbr`: Autodesk Fusion 360 library.
- `cleanroom/model.step`: 3D CAD STEP AP214 file.
- `cleanroom/model.glb`: WebGL GLB 3D model.
- `cleanroom/footprint.svg`: 2D PCB land pattern SVG.
- `cleanroom/pinout.svg`: IEEE-315 schematic symbol SVG.
- `datasheet.pdf`: Original datasheet PDF document.

---

## 8. Concrete Examples for AI Agents

### Python Example: Fetching a Pinout Table
```python
import requests

part_id = "C6553339"  # ESP32-S2-SOLO-2U-N4R2
url = f"https://chipdocs.org/api/v1/components/{part_id}"
resp = requests.get(url).json()

report = resp["report"]
print(f"Component: {report['mpn']} ({report['package']}) - {report['manufacturer']}")
print("--- Pinout ---")
for pin in report["pins"]:
    print(f"Pin {pin['pin_number']:2s}: {pin['pin_name']:12s} [{pin['electrical_type']:10s}] - {pin['primary_function']}")
```

### Python Example: Fetching Direct Markdown for LLM Context
```python
import requests

url = "https://chipdocs.org/api/v1/components/C8734/markdown"
md = requests.get(url).text
print(md)
```

### Node.js Example: Downloading KiCad Library
```javascript
import fs from 'fs';
import https from 'https';

const partId = 'C6553339';
const fileUrl = `https://chipdocs.org/api/v1/assets/${partId}/cleanroom/kicad.zip`;
const file = fs.createWriteStream(`${partId}_kicad.zip`);

https.get(fileUrl, (response) => {
  response.pipe(file);
  file.on('finish', () => {
    file.close();
    console.log(`KiCad library downloaded: ${partId}_kicad.zip`);
  });
});
```

---

## 9. Open Source Licensing & Compliance

- **Clean-Room Engineering**: All CAD assets, vector diagrams, and 3D models generated by chipdocs.org are clean-room syntheses created programmatically from published geometric dimensions.
- **Hardware License**: Licensed under the **CERN Open Hardware Licence Version 2 - Strongly Reciprocal (CERN-OHL-P-2.0)**.
- **Commercial & Personal Use**: Free for open-source and commercial PCB manufacturing.
- **Robots / LLM Crawlers**: Explicitly allowed in `robots.txt` for all major AI web agents (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, etc.).