# itztron/cyberx-project architecture

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

- Interactive diagram: https://gitdiagram.com/itztron/cyberx-project
- Repository: https://github.com/itztron/cyberx-project

## Overview

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: [`src/lib`](https://github.com/itztron/cyberx-project/tree/main/src/lib) (Client APIs), [`src/lib/hubApi.ts`](https://github.com/itztron/cyberx-project/blob/main/src/lib/hubApi.ts) (Hub API), [`server/routes/auth.js`](https://github.com/itztron/cyberx-project/blob/main/server/routes/auth.js) (Auth routes), [`src/App.tsx`](https://github.com/itztron/cyberx-project/blob/main/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser SPA"]
  node_src_main(("Bootstrap<br/>entrypoint<br/>[main.tsx]"))
  node_src_app["App shell<br/>router shell<br/>[App.tsx]"]
  node_pages["Pages<br/>routes"]
  node_components["UI components<br/>ui subsystem"]
  node_tools_data["Tools catalog<br/>content data<br/>[tools.ts]"]
  node_lib_boundary["Client APIs<br/>data layer"]
  node_supabase_client[("Supabase client<br/>client init<br/>[supabase.ts]")]
  node_auth_api["Auth API<br/>auth adapter<br/>[authApi.ts]"]
  node_otp_api["OTP client<br/>otp adapter<br/>[otpApi.ts]"]
  node_hub_api["Hub API<br/>domain client<br/>[hubApi.ts]"]
  node_git_vcs["Git VCS<br/>client vcs<br/>[gitVcs.ts]"]
  node_repo_agent["Tron agent<br/>agent loop<br/>[repoAgent.ts]"]
end

subgraph group_backend["Express API"]
  node_server_entry(("API server<br/>express app<br/>[index.js]"))
  node_server_auth["Auth routes<br/>otp/session api<br/>[auth.js]"]
  node_server_email["Email routes<br/>transactional mail<br/>[contact.js]"]
  node_server_mw_auth["JWT guard<br/>middleware<br/>[auth.js]"]
end

subgraph group_data["Supabase"]
  node_supabase_schema[("Migrations<br/>schema history")]
end

subgraph group_integrations["External Services"]
  node_openrouter(("OpenRouter<br/>llm gateway"))
  node_github(("GitHub<br/>repo import"))
  node_maps(("Maps APIs<br/>geo lookup"))
  node_smtp(("SMTP mail<br/>email delivery"))
end

node_src_main -->|"boots"| node_src_app
node_src_app -->|"routes"| node_pages
node_src_app -->|"composes"| node_components
node_pages -->|"reads"| node_tools_data
node_pages -->|"calls"| node_lib_boundary
node_components -->|"views"| node_git_vcs
node_components -->|"updates"| node_hub_api
node_lib_boundary -->|"uses"| node_supabase_client
node_lib_boundary -->|"auth"| node_auth_api
node_lib_boundary -->|"otp"| node_otp_api
node_lib_boundary -->|"domain"| node_hub_api
node_lib_boundary -->|"agent"| node_repo_agent
node_lib_boundary -->|"vcs"| node_git_vcs
node_repo_agent -->|"llm"| node_openrouter
node_repo_agent -->|"reads"| node_hub_api
node_server_entry -->|"mounts"| node_server_auth
node_server_entry -->|"mounts"| node_server_email
node_server_auth -->|"guards"| node_server_mw_auth
node_server_auth -->|"sends"| node_smtp
node_server_email -->|"sends"| node_smtp
node_server_auth -->|"uses"| node_supabase_schema
node_hub_api -->|"stores"| node_supabase_schema
node_hub_api -->|"imports"| node_github
node_hub_api -->|"looks up"| node_maps
node_supabase_schema -->|"enables"| node_supabase_client

click node_src_main "https://github.com/itztron/cyberx-project/blob/main/src/main.tsx"
click node_src_app "https://github.com/itztron/cyberx-project/blob/main/src/App.tsx"
click node_pages "https://github.com/itztron/cyberx-project/tree/main/src/pages"
click node_components "https://github.com/itztron/cyberx-project/tree/main/src/components"
click node_tools_data "https://github.com/itztron/cyberx-project/blob/main/src/data/tools.ts"
click node_lib_boundary "https://github.com/itztron/cyberx-project/tree/main/src/lib"
click node_supabase_client "https://github.com/itztron/cyberx-project/blob/main/src/lib/supabase.ts"
click node_auth_api "https://github.com/itztron/cyberx-project/blob/main/src/lib/authApi.ts"
click node_otp_api "https://github.com/itztron/cyberx-project/blob/main/src/lib/otpApi.ts"
click node_hub_api "https://github.com/itztron/cyberx-project/blob/main/src/lib/hubApi.ts"
click node_git_vcs "https://github.com/itztron/cyberx-project/blob/main/src/lib/gitVcs.ts"
click node_repo_agent "https://github.com/itztron/cyberx-project/blob/main/src/lib/repoAgent.ts"
click node_server_entry "https://github.com/itztron/cyberx-project/blob/main/server/index.js"
click node_server_auth "https://github.com/itztron/cyberx-project/blob/main/server/routes/auth.js"
click node_server_email "https://github.com/itztron/cyberx-project/blob/main/server/routes/contact.js"
click node_server_mw_auth "https://github.com/itztron/cyberx-project/blob/main/server/middleware/auth.js"
click node_supabase_schema "https://github.com/itztron/cyberx-project/tree/main/supabase/migrations"

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_src_main,node_src_app,node_pages,node_components,node_tools_data,node_lib_boundary,node_supabase_client,node_auth_api,node_otp_api,node_hub_api,node_git_vcs,node_repo_agent toneBlue
class node_server_entry,node_server_auth,node_server_email,node_server_mw_auth toneAmber
class node_supabase_schema toneMint
class node_openrouter,node_github,node_maps,node_smtp toneRose
```

## Components

### Browser SPA

Vite + React client, UI pages, and client-side data access

- [Bootstrap](https://github.com/itztron/cyberx-project/blob/main/src/main.tsx): entrypoint · Vite/React app startup and root wiring · `src/main.tsx`
- [App shell](https://github.com/itztron/cyberx-project/blob/main/src/App.tsx): router shell · Top-level client routing and application composition · `src/App.tsx`
- [Pages](https://github.com/itztron/cyberx-project/tree/main/src/pages): routes · Primary product screens for tools, repo workspace, auth, profiles, activity, and Tron · `src/pages`
- [UI components](https://github.com/itztron/cyberx-project/tree/main/src/components): ui subsystem · Navigation, repo interactions, notifications, and shared shadcn-style primitives · `src/components`
- [Tools catalog](https://github.com/itztron/cyberx-project/blob/main/src/data/tools.ts): content data · Public cybersecurity tools listing and details data · `src/data/tools.ts`
- [Client APIs](https://github.com/itztron/cyberx-project/tree/main/src/lib): data layer · Browser boundary for Supabase, auth, repo, agent, and external service adapters · `src/lib`
- [Supabase client](https://github.com/itztron/cyberx-project/blob/main/src/lib/supabase.ts): client init · Initializes the browser Supabase connection · `src/lib/supabase.ts`
- [Auth API](https://github.com/itztron/cyberx-project/blob/main/src/lib/authApi.ts): auth adapter · Routes password, OAuth, and session-related auth flows · `src/lib/authApi.ts`
- [OTP client](https://github.com/itztron/cyberx-project/blob/main/src/lib/otpApi.ts): otp adapter · Sends and verifies email OTP requests against the Express backend · `src/lib/otpApi.ts`
- [Hub API](https://github.com/itztron/cyberx-project/blob/main/src/lib/hubApi.ts): domain client · Repository, profile, activity, and custom hub operations · `src/lib/hubApi.ts`
- [Git VCS](https://github.com/itztron/cyberx-project/blob/main/src/lib/gitVcs.ts): client vcs · Client-side Git-compatible hashing and object modeling · `src/lib/gitVcs.ts`
- [Tron agent](https://github.com/itztron/cyberx-project/blob/main/src/lib/repoAgent.ts): agent loop · 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](https://github.com/itztron/cyberx-project/blob/main/server/index.js): express app · Lightweight Express runtime and middleware composition · `server/index.js`
- [Auth routes](https://github.com/itztron/cyberx-project/blob/main/server/routes/auth.js): otp/session api · OTP send/verify and privileged session creation · `server/routes/auth.js`
- [Email routes](https://github.com/itztron/cyberx-project/blob/main/server/routes/contact.js): transactional mail · Contact, follow, and report email endpoints · `server/routes/contact.js`
- [JWT guard](https://github.com/itztron/cyberx-project/blob/main/server/middleware/auth.js): middleware · Verifies backend-protected JWTs · `server/middleware/auth.js`

### Supabase

Auth, Postgres, Storage, Realtime, and schema migrations

- [Migrations](https://github.com/itztron/cyberx-project/tree/main/supabase/migrations): schema history · 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 · LLM gateway used by the Tron agent
- **GitHub**: repo import · External repository import and OAuth integration
- **Maps APIs**: geo lookup · Google Maps and LocationIQ location lookup services
- **SMTP mail**: email delivery · Mail transport used for OTP and transactional notifications

## Connections

- 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
