FDA + FCC + Health Canada Device Regulatory Explorer

One workspace for searching and monitoring public FDA medical-device records, FCC equipment authorizations, and Health Canada MDALL licences.

Start here

I want to…	Go here
Use the stable website	Main site
Review the newest internal version	Internal Use Only
Run the project locally	Local setup
Understand the code	Code tour
Understand the regulatory sources	Data sources
Release a change	Deployment guide

What the app does

The top navigation has two independent choices:

1. Source: FDA, FCC, or HC (Health Canada / MDALL)
2. View: Explorer or Monitoring

That creates six main workflows:

Workflow	What it is for
FDA Explorer	Search registration and listing records; filter establishments and products; customize columns; inspect record details; export CSVs.
FDA Monitoring	Review recent 510(k), recall, and adverse-event activity.
FCC Explorer	Search complete or partial FCC IDs; group results by confirmed grantee; inspect authorization history, exhibits, and evidence.
FCC Monitoring	Review recent original authorizations and FCC-labelled authorization changes for configured scopes.
HC Explorer	Search Health Canada MDALL licences, companies, device names, and identifiers.
HC Monitoring	Review recently issued and ended Canadian medical device licences.

Every workflow keeps source links and timestamps visible. FCC views also distinguish official source fields from app-derived labels and preserve the raw FCC record.

One codebase, two websites

Main and Internal Use Only are not duplicated applications. Both are built from this repository and deployed to separate Cloudflare Pages projects.

flowchart LR
  G["GitHub repository"] --> B["Shared production build"]
  B --> I["Internal Use Only"]
  B --> M["Main site"]
  I -->|"validate the same commit"| M

Loading

The normal release path is:

1. Build and test a commit.
2. Deploy it to Internal Use Only.
3. Verify all FDA, FCC and Health Canada routes.
4. Deploy that exact commit to Main.

This keeps the two sites consistent while giving unfinished changes a safe validation target.

Run it locally

You need Node.js 22.13 or newer and npm.

git clone https://github.com/ahmedbins/fda_device.git
cd fda_device
npm install
npm run dev

Open the local URL printed by the development server.

To validate the complete project:

npm test

That command creates a production build and runs the parsing, provenance, rendering, API-validation, and FDA regression tests.

Code tour

1. Routes stay small

The route files under app/fda/, app/fcc/ and app/hc/ select shared page components. Most feature code lives in a small number of clearly named modules:

File	Responsibility
app/page.tsx	FDA Explorer UI, query state, filters, result table, detail panels, and export behavior.
app/monitor-page.tsx	FDA Monitoring queries and the 510(k), recall, and adverse-event sections.
app/fcc-explorer-page.tsx	FCC search UI, filters, grouped grantees, authorization dossiers, imports, sharing, and CSV export.
app/fcc-monitor-page.tsx	FCC watchlists, date windows, activity summaries, authorization tables, and change categories.
app/mdall-explorer-page.tsx	Health Canada MDALL search, licence dossiers, company profiles, and CSV export.
app/mdall-monitor-page.tsx	Health Canada watchlists and recent issued/ended licences.
app/source-nav.tsx	Shared FDA/FCC/HC and Explorer/Monitoring navigation.
app/globals.css	Shared responsive visual system for every route.

2. Data logic is separate from the UI

The page components do not need to understand every source-specific detail:

File	Responsibility
app/fda-shared.ts	FDA constants, normalization helpers, and CSV utilities shared by FDA views.
app/fcc-core.ts	FCC XML/JSON parsing, date normalization, conservative purpose mapping, confirmed ID-part derivation, deduplication, grouping, and monitoring windows.
app/fcc-service.ts	Orchestrates the FCC snapshot, live request, server proxy, cache, grantee registry, and manual official-response import.
app/fcc-config.ts	Explicitly confirmed FCC presets and watchlist scopes.
app/fcc-official-snapshot.ts	Exact provenance-labelled FCC EAS records used for reliable covered-scope startup.
app/mdall-core.ts	Health Canada MDALL normalization, status labels, and grouping.
app/mdall-service.ts	Official MDALL API search, company joins, and device lookup.
app/api/fcc/search/route.ts	Server-side FCC proxy used by the full-stack build when the upstream service permits it.

The separation matters: parsing and source rules can be tested without rendering React, while UI work can consume one normalized record shape.

3. FDA request flow

flowchart LR
  U["FDA page"] --> Q["Build openFDA query"]
  Q --> A["openFDA API"]
  A --> N["Normalize source response"]
  N --> R["Filters, tables, details, CSV"]

Loading

FDA Explorer uses the Registration & Listing API. FDA Monitoring uses the 510(k), Recall, and Adverse Event APIs. Requests are made directly from the client to public openFDA endpoints.

4. FCC request flow

flowchart TD
  U["FCC search or watchlist"] --> L["Try live official FCC API"]
  L -->|Available| N["Normalize records"]
  L -->|Blocked| P["App proxy: official API, then fccid.io"]
  P -->|Index available| N
  P -->|Still unavailable| S["Bundled official snapshot"]
  S --> N
  N --> V["Explorer or Monitoring view"]

Loading

The FCC endpoint is public, but FCC/Akamai and browser CORS policies can block some automated request modes. The app treats that as a coverage limitation—not evidence that a record does not exist. Confirmed scopes load from the labelled official snapshot, and uncovered scopes can be imported from the official XML/JSON response.

5. Two production build paths share the same UI

• npm run build creates the full vinext/Worker build.
• npm run build:pages creates static multi-route output from cloudflare-spa/.
• Both builds import the same page components from app/.
• npm run deploy:internal sends the static build to the Internal Pages project.
• npm run deploy:main sends the same build to the Main Pages project.

Project structure

app/
  api/fcc/search/        FCC server-proxy route
  fda/                   FDA route entry points
  fcc/                   FCC route entry points
  hc/                    Health Canada MDALL route entry points
  *-page.tsx             Shared Explorer and Monitoring page components
  fda-shared.ts          FDA helpers
  fcc-core.ts            FCC parsing and normalization
  fcc-service.ts         FCC source orchestration
cloudflare-spa/          Static Pages entry points and Vite configuration
public/                  Icons and social-preview assets
tests/                   Unit, rendered-route, API, and regression tests
worker/                  Full-stack Cloudflare Worker entry point
docs/                    Deeper architecture, provenance, and release guides

Useful commands

Command	What it does
npm run dev	Start local development.
npm test	Build and run all automated tests.
npm run build	Create the full vinext production build.
npm run build:pages	Create the static Cloudflare Pages build.
npm run deploy:internal	Build and deploy Internal Use Only.
npm run deploy:main	Build and deploy Main.

Cloudflare deployment requires an authenticated Wrangler session with access to the existing Pages projects.

Regulatory data sources

Source	Used by
openFDA Device Registration & Listing	FDA Explorer
openFDA 510(k)	FDA Monitoring
openFDA Device Recall	FDA Monitoring
openFDA Device Adverse Events	FDA Monitoring
FCC Equipment Authorization System	FCC Explorer and Monitoring
FCC Open Data grantee registrations	Confirmed FCC grantee profiles
Health Canada MDALL API	HC Explorer and Monitoring

Read Data sources and provenance before changing source mappings, FCC presets, normalized categories, or snapshot records.

Adding or changing a feature

1. Start in the relevant page component for UI/state behavior.
2. Put reusable source parsing or normalization in fda-shared.ts or fcc-core.ts.
3. Keep upstream request/fallback logic in fcc-service.ts or the relevant FDA page module.
4. Preserve the raw regulatory value and label derived fields.
5. Add a focused test under tests/.
6. Run npm test.
7. Validate the change on Internal Use Only before promoting the same commit to Main.

More documentation

• Architecture
• Data sources and provenance
• Deployment and promotion
• Contributing

Security and accuracy

• Never commit access tokens, Cloudflare credentials, .env files, cookies, or private session data.
• Do not treat the Internal Use Only hostname as an authentication boundary.
• Do not invent missing regulatory fields or corporate relationships.
• Keep FCC-reported wording visible when showing a normalized category.
• Verify material regulatory decisions against the linked official record.