# reshmaprattipati21/shield-student-scan architecture

> Architecture diagram of the GitHub repository reshmaprattipati21/shield-student-scan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reshmaprattipati21/shield-student-scan
- Repository: https://github.com/reshmaprattipati21/shield-student-scan

## Overview

1. ScamShield is a route-based React 19 app built with TanStack Start and deployed as an SSR-capable Cloudflare Workers application. The architecture splits cleanly between shared UI/components, route modules, and a small set of domain libraries and integrations.

2. The top-level user experience is organized by routes in `src/routes`: a landing/dashboard page, auth page, and four scan/report modules (`url-checker`, `text-scanner`, `pdf-analyzer`, `reports`). `src/routeTree.gen.ts` is the generated routing map, so the app’s navigation structure is driven entirely by file-based routing.

3. `src/routes/__root.tsx` is the global composition layer. It is where app-wide providers, layout chrome, and error boundaries likely live. Shared navigation and shell components such as `Navbar` and `BackToDashboard` sit outside the route modules so they can be reused across pages.

4. The scam detection logic is centralized in `src/lib/scan-engine.ts`. This is the main domain engine for URL and text-based analysis, and it feeds the scanner pages with scores, highlighted phrases, and explanations. The visual risk output is rendered through components like `RiskGauge`, while other presentation helpers such as `RadarRing` and `CyberBg` provide the cyber-themed shell.

5. Scan results are also tracked locally in the browser. `src/lib/scan-history.ts` provides the history store, and the `ScanHistoryPanel` / `ScanHistoryDrawer` components expose that history to users. This is a client-side persistence boundary: history is for review and UX continuity, not a backend data source.

6. Supabase is the backend boundary for identity and crowdsourced data. The `src/integrations/supabase` folder contains client/server clients, auth middleware, an auth attacher, and generated types. This indicates the app uses separate server-side and browser-side Supabase access paths, with authentication context flowing through the TanStack Start runtime.

7. The `reports` module is the main persistent collaborative feature. It likely reads and writes scam-company reports to Supabase Postgres, with row-level security enforced by the migrations in `supabase/migrations`. The README confirms authenticated users are required, so the data flow is: user session → Supabase auth → RLS-protected report records.

8. The AI assistant is isolated from the rest of the client logic. `src/components/AIAssistant.tsx` is the floating chat surface, while `src/lib/chat.functions.ts` is the server-side gateway layer that talks to the AI provider. This separation keeps the model/API key off the client and makes AI interaction a server boundary rather than a direct browser call.

9. Authentication is a cross-cutting concern rather than a standalone page feature. `src/lib/auth-context.tsx` suggests a shared auth state provider that coordinates local app state with Supabase session state, while `src/routes/auth.tsx` handles sign-in/sign-up flows. That auth state likely gates access to reports and may personalize the scan history/UI.

10. The app is built as a mostly client-rendered UI with SSR support and server functions available where needed. `src/start.ts`, `src/router.tsx`, and the Supabase middleware files indicate the app bootstraps routing, auth, and server-side request handling together in the TanStack Start runtime.

11. The UI layer is heavily componentized. Most visual structure comes from `src/components` and the shadcn/ui primitives under `src/components/ui`, which provide the buttons, dialogs, drawers, tables, forms, and other interaction patterns used across scanners, reports, and auth screens. Tailwind CSS and the custom cyberpunk styling in `src/styles.css` define the visual system.

12. The main architectural boundaries to capture in a diagram are: route pages on the outside; shared UI/components in the middle; domain libraries for scan logic, history, and chat; and external services at the edge, namely Supabase for auth/data and Lovable AI for assistant responses. Browser-only state stays local, while authenticated collaboration and AI calls cross the server/backend boundary.

Main entry points: [`src/lib/scan-engine.ts`](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/scan-engine.ts) (Scan engine), [`src/components/BackToDashboard.tsx`](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/BackToDashboard.tsx) (Back link), [`src/router.tsx`](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/router.tsx) (Router), [`src/routes/__root.tsx`](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/__root.tsx) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_start["Start entry<br/>runtime bootstrap<br/>[start.ts]"]
  node_node_router["Router<br/>routing setup<br/>[router.tsx]"]
  node_node_routetree["Route map<br/>generated routing<br/>[routeTree.gen.ts]"]
  node_node_root["Root layout<br/>app shell<br/>[__root.tsx]"]
  node_node_index["Dashboard<br/>route page<br/>[index.tsx]"]
  node_node_auth["Auth page<br/>route page<br/>[auth.tsx]"]
  node_node_url["URL checker<br/>scan route<br/>[url-checker.tsx]"]
  node_node_text["Text scanner<br/>scan route<br/>[text-scanner.tsx]"]
  node_node_pdf["PDF analyzer<br/>scan route<br/>[pdf-analyzer.tsx]"]
  node_node_reports["Reports<br/>collab route<br/>[reports.tsx]"]
  node_node_navbar["Navbar<br/>shared navigation<br/>[Navbar.tsx]"]
  node_node_dashboard_link["Back link<br/>shared navigation"]
  node_node_ui_shell["UI kit<br/>ui primitives"]
  node_node_assistant["Assistant UI<br/>chat surface<br/>[AIAssistant.tsx]"]
  node_node_risk_gauge(("Risk gauge<br/>result viz<br/>[RiskGauge.tsx]"))
  node_node_scan_panel["Scan panel<br/>history ui"]
  node_node_scan_drawer["History drawer<br/>history ui"]
end

subgraph group_group_domain["Domain Logic"]
  node_node_scan_engine{{"Scan engine<br/>analysis core<br/>[scan-engine.ts]"}}
  node_node_scan_history[("History store<br/>client state<br/>[scan-history.ts]")]
  node_node_auth_context(("Auth context<br/>session state<br/>[auth-context.tsx]"))
  node_node_chat{{"AI gateway<br/>server function<br/>[chat.functions.ts]"}}
end

subgraph group_group_backend["Backend Boundary"]
  node_node_supabase_client["Supabase client<br/>browser client<br/>[client.ts]"]
  node_node_supabase_server["Supabase server<br/>server client<br/>[client.server.ts]"]
  node_node_supabase_auth["Auth middleware<br/>request auth<br/>[auth-middleware.ts]"]
  node_node_supabase_attacher["Auth attacher<br/>request auth<br/>[auth-attacher.ts]"]
  node_node_supabase_types["Supabase types<br/>generated schema<br/>[types.ts]"]
  node_node_migrations[("Migrations<br/>db schema")]
end

node_node_start -->|"bootstraps"| node_node_router
node_node_router -->|"uses"| node_node_routetree
node_node_router -->|"mounts"| node_node_root
node_node_root -->|"includes"| node_node_navbar
node_node_root -->|"uses"| node_node_ui_shell
node_node_index -->|"calls"| node_node_scan_engine
node_node_url -->|"calls"| node_node_scan_engine
node_node_text -->|"calls"| node_node_scan_engine
node_node_pdf -->|"uses"| node_node_ui_shell
node_node_reports -->|"reads/writes"| node_node_supabase_client
node_node_reports -->|"gates"| node_node_auth_context
node_node_auth -->|"authenticates"| node_node_supabase_client
node_node_auth_context -->|"hydrates"| node_node_supabase_server
node_node_supabase_auth -->|"coordinates"| node_node_supabase_attacher
node_node_supabase_auth -->|"protects"| node_node_supabase_server
node_node_supabase_types -.->|"types"| node_node_supabase_client
node_node_supabase_types -.->|"types"| node_node_supabase_server
node_node_migrations -->|"defines"| node_node_supabase_types
node_node_scan_engine -->|"feeds"| node_node_risk_gauge
node_node_scan_history -->|"exposes"| node_node_scan_panel
node_node_scan_history -->|"exposes"| node_node_scan_drawer
node_node_chat -->|"serves"| node_node_assistant
node_node_dashboard_link -.->|"navigates"| node_node_url
node_node_dashboard_link -.->|"navigates"| node_node_text
node_node_dashboard_link -.->|"navigates"| node_node_pdf
node_node_navbar -.->|"navigates"| node_node_index

click node_node_start "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/start.ts"
click node_node_router "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/router.tsx"
click node_node_routetree "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routeTree.gen.ts"
click node_node_root "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/__root.tsx"
click node_node_index "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/index.tsx"
click node_node_auth "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/auth.tsx"
click node_node_url "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/url-checker.tsx"
click node_node_text "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/text-scanner.tsx"
click node_node_pdf "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/pdf-analyzer.tsx"
click node_node_reports "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/reports.tsx"
click node_node_navbar "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/Navbar.tsx"
click node_node_dashboard_link "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/BackToDashboard.tsx"
click node_node_ui_shell "https://github.com/reshmaprattipati21/shield-student-scan/tree/main/src/components/ui"
click node_node_scan_engine "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/scan-engine.ts"
click node_node_scan_history "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/scan-history.ts"
click node_node_auth_context "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/auth-context.tsx"
click node_node_chat "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/chat.functions.ts"
click node_node_supabase_client "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/client.ts"
click node_node_supabase_server "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/client.server.ts"
click node_node_supabase_auth "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/auth-middleware.ts"
click node_node_supabase_attacher "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/auth-attacher.ts"
click node_node_supabase_types "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/types.ts"
click node_node_migrations "https://github.com/reshmaprattipati21/shield-student-scan/tree/main/supabase/migrations"
click node_node_assistant "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/AIAssistant.tsx"
click node_node_risk_gauge "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/RiskGauge.tsx"
click node_node_scan_panel "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/ScanHistoryPanel.tsx"
click node_node_scan_drawer "https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/ScanHistoryDrawer.tsx"

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_node_start,node_node_router,node_node_routetree,node_node_root,node_node_index,node_node_auth,node_node_url,node_node_text,node_node_pdf,node_node_reports,node_node_navbar,node_node_dashboard_link,node_node_ui_shell,node_node_assistant,node_node_risk_gauge,node_node_scan_panel,node_node_scan_drawer toneBlue
class node_node_scan_engine,node_node_scan_history,node_node_auth_context,node_node_chat toneAmber
class node_node_supabase_client,node_node_supabase_server,node_node_supabase_auth,node_node_supabase_attacher,node_node_supabase_types,node_node_migrations toneMint
```

## Components

### App Shell

Routing, composition, shared UI, and client-side experience.

- [Start entry](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/start.ts): runtime bootstrap · App startup and request/runtime wiring for TanStack Start. · `src/start.ts`
- [Router](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/router.tsx): routing setup · Client/server router configuration used by the app runtime. · `src/router.tsx`
- [Route map](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routeTree.gen.ts): generated routing · Generated file-based routing manifest for the route modules. · `src/routeTree.gen.ts`
- [Root layout](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/__root.tsx): app shell · Global composition layer for providers, layout chrome, and boundaries. · `src/routes/__root.tsx`
- [Dashboard](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/index.tsx): route page · Landing and dashboard experience. · `src/routes/index.tsx`
- [Auth page](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/auth.tsx): route page · Sign-in and sign-up flow. · `src/routes/auth.tsx`
- [URL checker](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/url-checker.tsx): scan route · Route for URL-based scam analysis. · `src/routes/url-checker.tsx`
- [Text scanner](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/text-scanner.tsx): scan route · Route for text-based scam analysis. · `src/routes/text-scanner.tsx`
- [PDF analyzer](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/pdf-analyzer.tsx): scan route · Route for document analysis. · `src/routes/pdf-analyzer.tsx`
- [Reports](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/routes/reports.tsx): collab route · Authenticated route for persistent scam-company reports. · `src/routes/reports.tsx`
- [Navbar](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/Navbar.tsx): shared navigation · Top-level navigation component reused across pages. · `src/components/Navbar.tsx`
- [Back link](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/BackToDashboard.tsx): shared navigation · Shared return-to-dashboard navigation affordance. · `src/components/BackToDashboard.tsx`
- [UI kit](https://github.com/reshmaprattipati21/shield-student-scan/tree/main/src/components/ui): ui primitives · Reusable shadcn/ui components for forms, dialogs, tables, drawers, and other controls. · `src/components/ui`
- [Assistant UI](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/AIAssistant.tsx): chat surface · Floating AI assistant component in the client UI. · `src/components/AIAssistant.tsx`
- [Risk gauge](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/RiskGauge.tsx): result viz · Visual risk output for scan results. · `src/components/RiskGauge.tsx`
- [Scan panel](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/ScanHistoryPanel.tsx): history ui · Browser history panel for previous scans. · `src/components/ScanHistoryPanel.tsx`
- [History drawer](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/components/ScanHistoryDrawer.tsx): history ui · Drawer presentation for scan history. · `src/components/ScanHistoryDrawer.tsx`

### Domain Logic

Scan analysis, history, auth state, and AI gateway logic.

- [Scan engine](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/scan-engine.ts): analysis core · Central scam detection logic for URL and text analysis. · `src/lib/scan-engine.ts`
- [History store](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/scan-history.ts): client state · Local browser history for past scans and review continuity. · `src/lib/scan-history.ts`
- [Auth context](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/auth-context.tsx): session state · Shared auth state provider coordinating local app state with Supabase sessions. · `src/lib/auth-context.tsx`
- [AI gateway](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/lib/chat.functions.ts): server function · Server-side chat function boundary for assistant requests. · `src/lib/chat.functions.ts`

### Backend Boundary

Supabase integration, SSR request handling, and persistent data.

- [Supabase client](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/client.ts): browser client · Client-side Supabase access path. · `src/integrations/supabase/client.ts`
- [Supabase server](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/client.server.ts): server client · Server-side Supabase access path for SSR and protected requests. · `src/integrations/supabase/client.server.ts`
- [Auth middleware](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/auth-middleware.ts): request auth · Middleware and auth attachment for TanStack Start requests. · `src/integrations/supabase/auth-middleware.ts`
- [Auth attacher](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/auth-attacher.ts): request auth · Helpers that attach Supabase auth context to requests. · `src/integrations/supabase/auth-attacher.ts`
- [Supabase types](https://github.com/reshmaprattipati21/shield-student-scan/blob/main/src/integrations/supabase/types.ts): generated schema · Generated database and auth type definitions. · `src/integrations/supabase/types.ts`
- [Migrations](https://github.com/reshmaprattipati21/shield-student-scan/tree/main/supabase/migrations): db schema · Supabase SQL migrations defining persistent data and RLS rules. · `supabase/migrations`

## Connections

- Start entry → Router: bootstraps · The app runtime initializes routing.
- Router → Route map: uses · Router is driven by the generated route manifest.
- Router → Root layout: mounts · Root route composes the global app shell.
- Root layout → Navbar: includes · Global navigation is part of the shell.
- Root layout → UI kit: uses · Root and routes rely on shared UI primitives.
- Dashboard → Scan engine: calls · Dashboard scan flows use the core analysis engine.
- URL checker → Scan engine: calls · URL scanner delegates analysis to the engine.
- Text scanner → Scan engine: calls · Text scanner delegates analysis to the engine.
- PDF analyzer → UI kit: uses · Document analysis UI is built from shared primitives.
- Reports → Supabase client: reads/writes · Reports interact with Supabase from the browser.
- Reports → Auth context: gates · Authenticated app state controls access and identity.
- Auth page → Supabase client: authenticates · Auth page initiates browser-side Supabase sign-in flows.
- Auth context → Supabase server: hydrates · Shared auth state is informed by server session access.
- Auth middleware → Auth attacher: coordinates · Request auth middleware uses attacher helpers.
- Auth middleware → Supabase server: protects · Middleware wraps protected SSR/server access.
- Supabase types → Supabase client: types · Generated types shape client database access.
- Supabase types → Supabase server: types · Generated types shape server database access.
- Migrations → Supabase types: defines · Database schema and RLS are the source for generated types.
- Scan engine → Risk gauge: feeds · Analysis output is rendered as risk visualization.
- History store → Scan panel: exposes · History store is surfaced in the panel UI.
- History store → History drawer: exposes · History store is surfaced in the drawer UI.
- AI gateway → Assistant UI: serves · Server-side AI gateway backs the client assistant surface.
- Back link → URL checker: navigates · Shared back link returns users to scan routes.
- Back link → Text scanner: navigates · Shared back link returns users to scan routes.
- Back link → PDF analyzer: navigates · Shared back link returns users to scan routes.
- Navbar → Dashboard: navigates · Navbar links into the landing/dashboard view.
