How reshmaprattipati21/shield-student-scan works
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: scan-engine.ts Scan engine · BackToDashboard.tsx Back link · router.tsx Router · __root.tsx Root layout
Components 27
App Shell
Routing, composition, shared UI, and client-side experience.
- Start entry · App startup and request/runtime wiring for TanStack Start.
src/start.ts - Router · Client/server router configuration used by the app runtime.
src/router.tsx - Route map · Generated file-based routing manifest for the route modules.
src/routeTree.gen.ts - Root layout · Global composition layer for providers, layout chrome, and boundaries.
src/routes/__root.tsx - Dashboard · Landing and dashboard experience.
src/routes/index.tsx - Auth page · Sign-in and sign-up flow.
src/routes/auth.tsx - URL checker · Route for URL-based scam analysis.
src/routes/url-checker.tsx - Text scanner · Route for text-based scam analysis.
src/routes/text-scanner.tsx - PDF analyzer · Route for document analysis.
src/routes/pdf-analyzer.tsx - Reports · Authenticated route for persistent scam-company reports.
src/routes/reports.tsx - Navbar · Top-level navigation component reused across pages.
src/components/Navbar.tsx - Back link · Shared return-to-dashboard navigation affordance.
src/components/BackToDashboard.tsx - UI kit · Reusable shadcn/ui components for forms, dialogs, tables, drawers, and other controls.
src/components/ui - Assistant UI · Floating AI assistant component in the client UI.
src/components/AIAssistant.tsx - Risk gauge · Visual risk output for scan results.
src/components/RiskGauge.tsx - Scan panel · Browser history panel for previous scans.
src/components/ScanHistoryPanel.tsx - History drawer · Drawer presentation for scan history.
src/components/ScanHistoryDrawer.tsx
Domain Logic
Scan analysis, history, auth state, and AI gateway logic.
- Scan engine · Central scam detection logic for URL and text analysis.
src/lib/scan-engine.ts - History store · Local browser history for past scans and review continuity.
src/lib/scan-history.ts - Auth context · Shared auth state provider coordinating local app state with Supabase sessions.
src/lib/auth-context.tsx - AI gateway · 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 · Client-side Supabase access path.
src/integrations/supabase/client.ts - Supabase server · Server-side Supabase access path for SSR and protected requests.
src/integrations/supabase/client.server.ts - Auth middleware · Middleware and auth attachment for TanStack Start requests.
src/integrations/supabase/auth-middleware.ts - Auth attacher · Helpers that attach Supabase auth context to requests.
src/integrations/supabase/auth-attacher.ts - Supabase types · Generated database and auth type definitions.
src/integrations/supabase/types.ts - Migrations · Supabase SQL migrations defining persistent data and RLS rules.
supabase/migrations
Connections 26
- 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.