How itztron/cyberx-project works
1. Overall shape
- This is a two-tier web platform in one repo: a Vite + React + TypeScript frontend at the root, plus a separate Express backend in server/ for OTP auth and notification-related email flows.
- The primary system of record is Supabase (Auth, Postgres, Storage, Realtime). The frontend talks to Supabase directly for most app data, while the Express server handles privileged operations.
2. Frontend application boundary
- The browser app is a single-page application built with React Router, Tailwind, and shadcn/ui primitives.
- src/App.tsx and src/main.tsx define app bootstrapping and route-level navigation.
- Pages in src/pages/ map to the product areas: homepage, tools catalog, dashboard, repository manager, Tron agent, profiles, activity, auth screens, and public profile views.
3. Core product subsystems in the UI
- The app is organized around a cybersecurity tools hub and a GitHub-like repository workspace.
- Reusable components in src/components/ support major interactions: repository branch switching, commit diff viewing, notification dropdowns, markdown README rendering, and the global navigation shell.
- src/data/tools.ts drives the public tools listing and detail pages.
4. Client-side data access layer
- src/lib/ is the main boundary between UI and external systems.
- supabase.ts initializes the Supabase client.
- authApi.ts, otpApi.ts, and apiBaseUrl.ts route auth calls to either Supabase or the Express backend.
- hubApi.ts is the main client for repository/profile/activity operations and wraps the app’s custom Git VCS behaviors.
- Separate adapters exist for external services: githubApi.ts, repoAgent.ts, googleMaps.ts, locationIQ.ts, hubApi.ts, and gitVcs.ts.
5. Authentication flow
- There are three auth paths exposed in /signin and /signup: password auth, GitHub OAuth, and email OTP.
- Password and OAuth are handled through Supabase Auth.
- OTP is a custom flow: frontend sends email to the Express server, the server generates and stores the token, emails the code, verifies it, then creates a real Supabase session via a magic-link style token exchange.
6. Express backend responsibilities
- server/index.js is a lightweight API service with middleware and route modules.
- server/routes/auth.js owns OTP send/verify and privileged session creation.
- server/routes/contact.js, follow.js, and report.js send transactional emails for contact, follow, and moderation/reporting events.
- server/middleware/auth.js verifies JWTs for backend-protected routes.
- This backend is deliberately narrow: it does not replace Supabase; it fills the gap for secure email/JWT/SMTP flows.
7. Supabase as the persistent backend
- Supabase hosts authentication, relational data, file/storage-backed profile assets, and realtime notifications.
- The supabase/migrations/ folder is the architecture-defining schema history. It adds:
- auth/activity tables,
- repository and Git VCS tables,
- OTP token storage,
- user profile fields,
- social follow/fork notifications,
- Tron chat state,
- imported GitHub repo records.
- The data model is therefore split between user identity/session state in Supabase Auth and application domain data in Postgres.
8. Git VCS subsystem
- The repository manager is backed by a browser-native Git-compatible layer, not by a server-side Git binary.
- src/lib/gitVcs.ts computes Git-style SHA-1 hashes and commit/tree/blob metadata on the client side.
- src/lib/hubApi.ts and the Supabase tables store repository refs, commits, file snapshots, and merge history.
- UI surfaces for this subsystem are the repository page, branch selector, diff viewer, and inline file editor.
9. Tron AI agent subsystem
- /tron is a separate interaction model from the repository UI.
- src/lib/repoAgent.ts orchestrates an agentic loop that can inspect repositories, search code, read history, and propose changes.
- The agent uses OpenRouter as the LLM gateway and can call multiple repository tools before returning an answer.
- Write actions are gated by explicit confirmation, so Tron is read-mostly until the user approves a commit operation.
10. Social and realtime flow
- User follows and repository forks generate in-app notifications stored in Supabase.
- The notification bell subscribes to Supabase Realtime so updates appear without polling.
- Public profile pages allow social actions such as follow and fork, linking the profile subsystem with repository and notification data.
11. External service integrations
- The app integrates several third-party services that shape architecture:
- OpenRouter for Tron AI,
- GitHub for repository import,
- Google Maps + LocationIQ for profile location lookup,
- SMTP/Nodemailer for OTP and social email notifications.
- These integrations are isolated behind small client helpers or backend routes so the rest of the UI remains service-agnostic.
12. Deployment and runtime boundaries
- The frontend can be deployed as a static build, but the repo also supports combined deployment where Express serves the built frontend and API together.
- The repo includes deployment docs and scripts for Azure App Service, AWS ECS Express mode, and Google Cloud Run.
- CI files and SonarQube scripts indicate the project is designed for both local development and automated quality/deployment pipelines.
13. Useful diagram takeaway
- For an architecture diagram, the main boxes are:
- Browser SPA
- Express auth/email API
- Supabase Auth/Postgres/Realtime/Storage
- External APIs: OpenRouter, GitHub, Google Maps, LocationIQ, SMTP
- The key data flows are:
- browser ↔ Supabase for most app data,
- browser ↔ Express for OTP and email-triggered flows,
- browser ↔ OpenRouter for Tron,
- Supabase Realtime → notification UI,
- migrations → schema that enables repository, social, and OTP features.
Main entry points: lib Client APIs · hubApi.ts Hub API · auth.js Auth routes · App.tsx App shell
Components 21
Browser SPA
Vite + React client, UI pages, and client-side data access
- Bootstrap · Vite/React app startup and root wiring
src/main.tsx - App shell · Top-level client routing and application composition
src/App.tsx - Pages · Primary product screens for tools, repo workspace, auth, profiles, activity, and Tron
src/pages - UI components · Navigation, repo interactions, notifications, and shared shadcn-style primitives
src/components - Tools catalog · Public cybersecurity tools listing and details data
src/data/tools.ts - Client APIs · Browser boundary for Supabase, auth, repo, agent, and external service adapters
src/lib - Supabase client · Initializes the browser Supabase connection
src/lib/supabase.ts - Auth API · Routes password, OAuth, and session-related auth flows
src/lib/authApi.ts - OTP client · Sends and verifies email OTP requests against the Express backend
src/lib/otpApi.ts - Hub API · Repository, profile, activity, and custom hub operations
src/lib/hubApi.ts - Git VCS · Client-side Git-compatible hashing and object modeling
src/lib/gitVcs.ts - Tron agent · Agentic repository assistant with tool use and confirm-before-write behavior
src/lib/repoAgent.ts
Express API
Narrow server for OTP and transactional email flows
- API server · Lightweight Express runtime and middleware composition
server/index.js - Auth routes · OTP send/verify and privileged session creation
server/routes/auth.js - Email routes · Contact, follow, and report email endpoints
server/routes/contact.js - JWT guard · Verifies backend-protected JWTs
server/middleware/auth.js
Supabase
Auth, Postgres, Storage, Realtime, and schema migrations
- Migrations · Postgres schema for auth, repositories, profiles, notifications, OTP, and Tron state
supabase/migrations
External Services
Third-party APIs used by the app and agent
- OpenRouter · LLM gateway used by the Tron agent
- GitHub · External repository import and OAuth integration
- Maps APIs · Google Maps and LocationIQ location lookup services
- SMTP mail · Mail transport used for OTP and transactional notifications
Connections 25
- Bootstrap → App shell: boots · Application startup mounts the router shell
- App shell → Pages: routes · App shell renders all route-level screens
- App shell → UI components: composes · Shared chrome and interaction widgets support the shell
- Pages → Tools catalog: reads · Tools pages are driven by the public catalog data
- Pages → Client APIs: calls · Pages use client adapters for data and side effects
- UI components → Git VCS: views · Repo UI uses client-side Git primitives for diffs and refs
- UI components → Hub API: updates · Repo and social controls call the hub client
- Client APIs → Supabase client: uses · Most app data flows through the Supabase client
- Client APIs → Auth API: auth · Password and OAuth auth are routed through the auth adapter
- Client APIs → OTP client: otp · Email OTP flow is delegated to the backend API
- Client APIs → Hub API: domain · Hub client handles repository, profile, and activity operations
- Client APIs → Tron agent: agent · Tron page invokes the agent orchestration layer
- Client APIs → Git VCS: vcs · Git-compatible object handling supports repo workflows
- Tron agent → OpenRouter: llm · Tron uses OpenRouter for model access
- Tron agent → Hub API: reads · Agent inspects repositories and history through hub operations
- API server → Auth routes: mounts · Express server exposes the OTP/session routes
- API server → Email routes: mounts · Express server exposes transactional mail routes
- Auth routes → JWT guard: guards · Privileged session operations are protected by JWT middleware
- Auth routes → SMTP mail: sends · OTP codes are delivered through email transport
- Email routes → SMTP mail: sends · Contact, follow, and report messages are emailed
- Auth routes → Migrations: uses · OTP/token persistence depends on Supabase schema
- Hub API → Migrations: stores · Repository, profile, activity, notification, and social data live in Postgres
- Hub API → GitHub: imports · Imported repositories originate from GitHub
- Hub API → Maps APIs: looks up · Profile location fields use geo lookup adapters
- Migrations → Supabase client: enables · Schema supports auth, realtime, storage, and app data access