TechAPI organizes smartphone, SoC, GPU, CPU and brand specifications in a shared JSON format. It normalizes vendor names and units, validates the data, and publishes it through a website and API.

Scope

• The TechAPI repository owns source data, contribution rules, a lightweight validator and the public Astro site.
• TechEngine owns full validation, SQLModel seeding, the FastAPI read API, static JSON dumps, coverage checks and ingestion automation.
• Data is separated into brand, SoC, smartphone, GPU and CPU categories.

Ownership

The work includes data paths, JSON schemas, validation jobs, and API and website deployment. The dataset and API are published for use in other projects.

Current status: publicly available. Completed and planned work are explicitly separated in roadmap.md.

1. Repository and ownership boundary

TechAPI/data is the canonical store for smartphone, SoC, GPU, CPU and brand JSON. Validation, loading and delivery live in TechEngine so data licensing and release cadence remain independent from executable code. Each repository pins the other by submodule SHA, making the engine-data pair reproducible.

2. Contribution and validation pipeline

A dependency-free validator first checks directory rules, slugs, required values and source_urls on a data pull request. TechEngine then applies range, duplicate, reference-integrity and cross-field rules. Failures report the record path and reason in CI; only changes that pass every gate move from develop to main.

3. Runtime read paths

The TechEngine loader reads the pinned TechAPI checkout into common domain models. One path maps records to SQLModel entities, seeds SQLite or PostgreSQL and serves FastAPI queries. A second path emits a versioned static JSON tree and coverage metadata from the same validated snapshot. Database and dump delivery never create competing data sources.

4. Consumer and deployment boundary

FastAPI serves filtered queries, while static dumps support CDNs, application builds and the Astro explorer without a running server. The documentation site stays available during API downtime, and downstream products such as TechPicks can pin a curated build catalog. Public read delivery is deliberately kept separate from any authenticated write surface.

5. Refresh and failure behavior

Scheduled workflows collect upstream material into a staged change and open a dated pull request only after the same integrity gates pass. Actor, commit-marker and no-change checks prevent submodule webhook loops. When an upstream format changes, collection is partial or schema validation fails, the last public snapshot remains intact and the pipeline stops at a reviewable pull request.

6. Data contract and ownership

Category JSON is the source of truth while _verify ledger, caches and status own verification history. The Astro site is a read-only consumer and does not own API-server state, allowing data and presentation changes to ship independently.

7. Performance and scale bottlenecks

Schema, URL and cross-reference checks that traverse the full tree grow with the dataset. Cache hit rate, changed-file incremental validation and static v1 artifact size need measurement; throughput and P95 build time have not been measured.

8. Security, observability and debt

CODEOWNERS and PR gates make supply-chain changes reviewable, while long-term source-URL validity and submodule revisions remain separate risks. Failed workflows and the ledger provide audit evidence, but availability SLOs and public-endpoint monitoring are missing.

Separate data from the engine

A monorepo is simpler, but it couples code and data licensing and release cadence. Keeping CC-BY-SA data separate from the MIT engine makes mirroring and reuse explicit, at the cost of synchronization automation.

Offer an API and static dumps

FastAPI supports flexible queries but requires a running service. Static dumps are less expressive but cheap and reliable on a CDN. Both are generated from the same validated data so consumers can choose the appropriate delivery model.

Treat paths as part of the contract

Category, manufacturer, year and segment appear in directory paths, while slugs are restricted to kebab-case. Moves become deliberate migrations, but reviewers can identify placement and duplication without executing the engine.

Require sources

Every record must include canonical source_urls. Contribution speed is intentionally traded for traceability and reviewable evidence.

Automated checks

• python -m app.validate uses only the Python standard library and runs quickly on every data pull request.
• TechEngine runs unit and integration tests, linting and type checks in a separate workflow.
• Full-data checks cover schema shape, value ranges, slug and reference uniqueness, and required sources.
• Coverage jobs compare curated records with upstream catalogs and publish gap reports.

Reproduction path

The same dataset can be validated, seeded into a database, served with FastAPI and exported as a static dump. Docker Compose provides PostgreSQL while the default local path uses SQLite.

Known limits

Vendor page changes and region-specific naming still require collector maintenance. No public single-number accuracy score covers the entire dataset, so overall accuracy is marked not measured. Automation verifies provenance and structure but cannot guarantee that an upstream source is itself correct.

Completed

• Five data categories and common path rules
• Lightweight pull-request validation and full integrity checks
• FastAPI read API, SQLModel seeding and static JSON dumps
• Dataset and engine sites with GitHub Actions delivery
• Bidirectional submodule revision synchronization

In progress

• Gap reports between upstream catalogs and curated data
• Stabilization of scheduled benchmark refresh and new-SKU drafting

Planned

• Additional verifiable sources such as Intel ARK, AMD product pages and TechPowerUp
• More visible data-quality history and algorithm versions
• Clearer version policies for downstream consumers

Out of scope

Authenticated write APIs and commerce workflows are not current goals. TechAPI remains focused on verifiable public data and dependable read delivery.