Platform Overview
The Webyes Auditor platform has three independently deployable layers: two React frontend apps sharing a common library, and one FastAPI backend serving them both.full-suite
React + Vite SPA · Port 5173 · Full feature set including billing and team management
a11y
React + Vite SPA · Port 5174 · Accessibility-only standalone product
auditor-backend
FastAPI · Port 8000 · Single API serving both apps
packages/common (UI library) and packages/focus-order (accessibility tool), and both talk to the same backend over HTTPS REST.
Component Responsibilities
Key Data Flows
1. User Authentication
1. User Authentication
1
Login request
Browser sends
POST /api/auth/login with email and password.2
Token issued
Backend validates credentials, signs a JWT (RS256), stores it in Redis, and returns
{ access_token }.3
Authenticated requests
Frontend stores the token in a cookie. All subsequent API calls include
Authorization: Bearer <token>.2. Website Audit Scan
2. Website Audit Scan
1
Trigger scan
User initiates a scan →
POST /api/website-audit/. Backend creates a WebsiteAudit record with status=in_progress.2
Scanner called
Backend calls the external Lighthouse Scanner API with the website URL and a webhook callback URL.
3
Frontend polls
Frontend polls
GET /api/website-audit/latest-audit-status/ every few seconds to track progress.4
Results received
Scanner finishes and POSTs results back to the backend webhook. Backend saves
LighthouseAudit records and stores full JSON in S3.5
Results available
WebsiteAudit.status → completed. Frontend fetches results from /api/results/.3. Report Generation
3. Report Generation
1
Request report
User requests a PDF report →
GET /api/report/.2
Data compiled
Backend aggregates audit data across all pages and metrics.
3
S3 URL returned
A presigned S3 URL is returned — valid for 2 minutes. Frontend opens it for download.
4. Billing (Stripe)
4. Billing (Stripe)
1
Select plan
User picks a subscription plan →
POST /api/stripe/create-checkout-session/.2
Stripe checkout
Backend creates a Stripe Checkout Session and returns the redirect URL. Frontend redirects the user.
3
Payment completed
Stripe sends a webhook to
POST /api/stripe/webhook. Backend verifies the signature, creates UserPlanPurchase, and updates subscription limits.4
Redirect
User is sent to the success or failure URL configured in env vars.
5. AI Fix Suggestion (Gemini)
5. AI Fix Suggestion (Gemini)
1
Request fix
Frontend sends
POST /api/solutions/ with the issue rule ID and HTML snippet.2
Prompt built
Backend selects the right prompt template for the issue type and calls Gemini 2.0 Flash.
3
Fix stored
AI response
{ current_code, correct_code, explanation } is cached in S3 for 180 days.4
Fix returned
A presigned S3 URL is returned to the frontend.