# shawaiz-project/trace-scope architecture

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

- Interactive diagram: https://gitdiagram.com/shawaiz-project/trace-scope
- Repository: https://github.com/shawaiz-project/trace-scope

## Overview

SpeedTest Pro is a browser-based network diagnostics product with a FastAPI backend and Supabase Edge Functions in the tree. The main user flow is to run a speed test, view measurements and a quality assessment, then review history or export/share results. The sampled frontend shows the test panel calling the test and scoring libraries; backend router internals and most UI integrations were not sampled, so those connections are left out.

Main entry points: [`src/components/SpeedTestPanel.tsx`](https://github.com/shawaiz-project/trace-scope/blob/main/src/components/SpeedTestPanel.tsx) (Test panel), [`src/pages/Index.tsx`](https://github.com/shawaiz-project/trace-scope/blob/main/src/pages/Index.tsx) (Test dashboard), [`backend/main.py`](https://github.com/shawaiz-project/trace-scope/blob/main/backend/main.py) (FastAPI app), [`src/App.tsx`](https://github.com/shawaiz-project/trace-scope/blob/main/src/App.tsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routes<br/>[App.tsx]"]
  node_index["Test dashboard<br/>[Index.tsx]"]
  node_device["Device details<br/>[deviceInfo.ts]"]
end

subgraph group_testing["Network testing"]
  node_testpanel["Test panel<br/>[SpeedTestPanel.tsx]"]
  node_testengine["Test engine<br/>[speedtest.ts]"]
  node_regions["Server regions<br/>[serverRegions.ts]"]
end

subgraph group_insights["Results and reports"]
  node_history["Test history<br/>[speedHistory.ts]"]
  node_score["Quality scoring<br/>[networkScoring.ts]"]
  node_scoreview["Score display"]
  node_reportui["Report download<br/>[ReportDownload.tsx]"]
  node_reportgen["Report generator<br/>[reportGenerator.ts]"]
  node_shareui["Share results"]
  node_sharedpage["Shared report page<br/>[SharedReport.tsx]"]
end

subgraph group_backend["API services"]
  node_backendapp["FastAPI app<br/>[main.py]"]
  node_speedrouter["Speed test routes<br/>[speedtest.py]"]
  node_networkrouter["Network routes<br/>[network.py]"]
  node_sharerouter["Share routes<br/>[share.py]"]
  node_ipservice["IP lookup service<br/>[ip_service.py]"]
  node_scoringservice["Quality scoring<br/>[scoring_service.py]"]
  node_cardservice["Card generation<br/>[card_generator.py]"]
  node_sharedb[("Share data store<br/>[share_db.py]")]
  node_ipfunction["IP info function<br/>[index.ts]"]
  node_downloadfunction["Download test function<br/>[index.ts]"]
  node_pingfunction["Ping test function<br/>[index.ts]"]
  node_uploadfunction["Upload test function<br/>[index.ts]"]
end

node_user(("User"))
node_externalgeo["IP geolocation provider"]

node_user -->|"opens app"| node_app
node_app -->|"routes to"| node_index
node_index -->|"gets device details"| node_device
node_index -->|"renders test"| node_testpanel
node_testpanel -->|"runs test"| node_testengine
node_testpanel -->|"saves result"| node_history
node_testpanel -->|"calculates score"| node_score
node_testpanel -->|"displays score"| node_scoreview
node_index -->|"offers download"| node_reportui
node_reportui -->|"generates report"| node_reportgen
node_reportgen -->|"calculates score"| node_score
node_app -->|"routes shared report"| node_sharedpage
node_backendapp -->|"includes routes"| node_speedrouter
node_backendapp -->|"includes routes"| node_networkrouter
node_backendapp -->|"includes routes"| node_sharerouter
node_ipfunction -->|"looks up address"| node_externalgeo

click node_app "https://github.com/shawaiz-project/trace-scope/blob/main/src/App.tsx"
click node_index "https://github.com/shawaiz-project/trace-scope/blob/main/src/pages/Index.tsx"
click node_device "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/deviceInfo.ts"
click node_testpanel "https://github.com/shawaiz-project/trace-scope/blob/main/src/components/SpeedTestPanel.tsx"
click node_testengine "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/speedtest.ts"
click node_regions "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/serverRegions.ts"
click node_history "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/speedHistory.ts"
click node_score "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/networkScoring.ts"
click node_scoreview "https://github.com/shawaiz-project/trace-scope/blob/main/src/components/NetworkQualityScore.tsx"
click node_reportui "https://github.com/shawaiz-project/trace-scope/blob/main/src/components/ReportDownload.tsx"
click node_reportgen "https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/reportGenerator.ts"
click node_shareui "https://github.com/shawaiz-project/trace-scope/blob/main/src/components/ShareReportLink.tsx"
click node_sharedpage "https://github.com/shawaiz-project/trace-scope/blob/main/src/pages/SharedReport.tsx"
click node_backendapp "https://github.com/shawaiz-project/trace-scope/blob/main/backend/main.py"
click node_speedrouter "https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/speedtest.py"
click node_networkrouter "https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/network.py"
click node_sharerouter "https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/share.py"
click node_ipservice "https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/ip_service.py"
click node_scoringservice "https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/scoring_service.py"
click node_cardservice "https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/card_generator.py"
click node_sharedb "https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/share_db.py"
click node_ipfunction "https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/ip-info/index.ts"
click node_downloadfunction "https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-download/index.ts"
click node_pingfunction "https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-ping/index.ts"
click node_uploadfunction "https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-upload/index.ts"

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_index,node_device,node_user toneBlue
class node_testpanel,node_testengine,node_regions toneAmber
class node_history,node_score,node_scoreview,node_reportui,node_reportgen,node_shareui,node_sharedpage toneMint
class node_backendapp,node_speedrouter,node_networkrouter,node_sharerouter,node_ipservice,node_scoringservice,node_cardservice,node_sharedb,node_ipfunction,node_downloadfunction,node_pingfunction,node_uploadfunction toneRose
class node_externalgeo toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/shawaiz-project/trace-scope/blob/main/src/App.tsx): `src/App.tsx`
- [Test dashboard](https://github.com/shawaiz-project/trace-scope/blob/main/src/pages/Index.tsx): `src/pages/Index.tsx`
- [Device details](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/deviceInfo.ts): `src/lib/deviceInfo.ts`

### Network testing

- [Test panel](https://github.com/shawaiz-project/trace-scope/blob/main/src/components/SpeedTestPanel.tsx): `src/components/SpeedTestPanel.tsx`
- [Test engine](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/speedtest.ts): `src/lib/speedtest.ts`
- [Server regions](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/serverRegions.ts): `src/lib/serverRegions.ts`

### Results and reports

- [Test history](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/speedHistory.ts): `src/lib/speedHistory.ts`
- [Quality scoring](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/networkScoring.ts): `src/lib/networkScoring.ts`
- [Score display](https://github.com/shawaiz-project/trace-scope/blob/main/src/components/NetworkQualityScore.tsx): `src/components/NetworkQualityScore.tsx`
- [Report download](https://github.com/shawaiz-project/trace-scope/blob/main/src/components/ReportDownload.tsx): `src/components/ReportDownload.tsx`
- [Report generator](https://github.com/shawaiz-project/trace-scope/blob/main/src/lib/reportGenerator.ts): `src/lib/reportGenerator.ts`
- [Share results](https://github.com/shawaiz-project/trace-scope/blob/main/src/components/ShareReportLink.tsx): `src/components/ShareReportLink.tsx`
- [Shared report page](https://github.com/shawaiz-project/trace-scope/blob/main/src/pages/SharedReport.tsx): `src/pages/SharedReport.tsx`

### API services

- [FastAPI app](https://github.com/shawaiz-project/trace-scope/blob/main/backend/main.py): `backend/main.py`
- [Speed test routes](https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/speedtest.py): `backend/routers/speedtest.py`
- [Network routes](https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/network.py): `backend/routers/network.py`
- [Share routes](https://github.com/shawaiz-project/trace-scope/blob/main/backend/routers/share.py): `backend/routers/share.py`
- [IP lookup service](https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/ip_service.py): `backend/services/ip_service.py`
- [Quality scoring](https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/scoring_service.py): `backend/services/scoring_service.py`
- [Card generation](https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/card_generator.py): `backend/services/card_generator.py`
- [Share data store](https://github.com/shawaiz-project/trace-scope/blob/main/backend/services/share_db.py): `backend/services/share_db.py`
- [IP info function](https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/ip-info/index.ts): `supabase/functions/ip-info/index.ts`
- [Download test function](https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-download/index.ts): `supabase/functions/speedtest-download/index.ts`
- [Ping test function](https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-ping/index.ts): `supabase/functions/speedtest-ping/index.ts`
- [Upload test function](https://github.com/shawaiz-project/trace-scope/blob/main/supabase/functions/speedtest-upload/index.ts): `supabase/functions/speedtest-upload/index.ts`

### Other components

- **User**
- **IP geolocation provider**

## Connections

- User → App routes: opens app
- App routes → Test dashboard: routes to
- Test dashboard → Device details: gets device details
- Test dashboard → Test panel: renders test
- Test panel → Test engine: runs test
- Test panel → Test history: saves result
- Test panel → Quality scoring: calculates score
- Test panel → Score display: displays score
- Test dashboard → Report download: offers download
- Report download → Report generator: generates report
- Report generator → Quality scoring: calculates score
- App routes → Shared report page: routes shared report
- FastAPI app → Speed test routes: includes routes
- FastAPI app → Network routes: includes routes
- FastAPI app → Share routes: includes routes
- IP info function → IP geolocation provider: looks up address