# cobrother-official/cobrother_frontend architecture

> Architecture diagram of the GitHub repository cobrother-official/cobrother_frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cobrother-official/cobrother_frontend
- Repository: https://github.com/cobrother-official/cobrother_frontend

## Overview

1. **Overall shape**
   - This repository is a **React 18 + Vite single-page application** for the CoBrother marketplace.
   - It is the **browser frontend only**: business data, auth, auctions, listings, and AI features are served by an external **FastAPI backend**.
   - Production hosting is on **Vercel**, with backend API calls routed to Render-hosted services.

2. **Routing and page composition**
   - `src/pages/` contains the **route-level screens**: home, domains, ventures, technology/co-creation, creator community, auctions, dashboards, auth flows, and admin/operator pages.
   - `src/components/layout/` and common navigation components provide the **shell** around those pages.
   - Protected areas such as dashboard/admin flows are gated through `src/components/auth/ProtectedRoute.jsx`.

3. **Feature boundaries**
   - The UI is organized around the platform’s core business domains:
     - **Domains**: marketplace, registration, transfer, verification, storefront
     - **Ventures**: venture listings, bids, deals, verification, profile sections
     - **Technology / co-creation**: software listings, auctions, demo/verification flows
     - **Creator/community**: creator listings, community auctions, profile completion
     - **Auctions**: shared auction hub and category-specific auction flows
   - Each domain has its own page components, specialized cards/modals, and helper utilities.

4. **Data access layer**
   - `src/api/` is the **network boundary**: Axios client setup plus feature-specific service modules.
   - `src/utils/*` contains many **business adapters and calculators** that shape API data for the UI: pricing, verification, listing visibility, auction fees, domain display, analytics, and navigation helpers.
   - The backend API origin is resolved through `src/config/urls.js`, which is important because OAuth and WebSocket endpoints must target the backend host, not the frontend host.

5. **Request and environment flow**
   - In local development, Vite proxies `/api`, `/oauth2`, and `/ws` to the backend.
   - In production, `vercel.json` rewrites API routes to the backend and preserves SPA client-side routing.
   - Environment variables in `.env.*` control the backend URL and app origin, so the frontend can switch cleanly between local and production deployments.

6. **Global application state**
   - Cross-cutting state is handled by React context in `src/context/`:
     - **AuthContext** for sign-in/session state
     - **CurrencyContext** for display and conversion
     - **LanguageContext** for localization
     - **CookieConsentContext** for privacy/cookie preferences
   - These contexts affect almost every route because they control permissions, formatting, locale, and consent-driven UI.

7. **Realtime and live updates**
   - Auction and notification experiences are supported by **SockJS + STOMP** through hooks like `useNotificationSocket`, `useAuction`, `useCommunityAuction`, and `useSoftwareAuction`.
   - This is the main realtime boundary in the app: the browser subscribes to backend events for live auction status, notifications, and similar updates.

8. **Localization and regional behavior**
   - The app is multi-lingual through **i18next / react-i18next**.
   - Translation resources live in `src/i18n/locales/`, with helper scripts to sync/apply translations.
   - `src/context/LanguageContext.jsx`, locale utilities, and region-specific currency formatting make language and currency part of the core UX, not just presentation.

9. **Shared UI system**
   - `src/components/common/` contains reusable primitives: buttons, modals, loaders, banners, navbars, search bars, tooltips, consent UI, and bot-protection widgets.
   - `src/components/home/`, `src/components/listings/`, `src/components/ai/`, `src/components/analytics/`, and similar folders hold **feature-specific presentational components**.
   - Styling is a mix of **Tailwind CSS** and targeted CSS files in `src/styles/`, with Framer Motion used for page and section animation.

10. **Integrations with external services**
   - **Google OAuth** is part of the auth flow and routes through the backend.
   - **AI domain generation** and related storefront experiences are frontend surfaces over backend AI services.
   - **Payment/payout flows** are supported by utility code for checkout and payout settings, indicating an external payment provider integration.
   - Bot protection and consent mechanisms are also first-class parts of the app boundary.

11. **Analytics and dashboards**
   - The app includes multiple dashboards and reporting views: user dashboards, admin dashboards, operations views, platform analytics, profile analytics, and venture/domain analytics.
   - Charts are rendered with **Recharts**, and the data is pre-shaped by utility modules before it reaches chart components.
   - This makes analytics a separate UI subsystem rather than just another page.

12. **Build, deployment, and quality gates**
   - The frontend is built with Vite and deployed through **Vercel**; GitHub Actions run frontend tests and deployment workflows.
   - Tests are present for critical utilities and auth/protected-route behavior, showing that route protection, formatting logic, and business rules are treated as core frontend concerns.

Main entry points: [`src/main.jsx`](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/main.jsx) (Main), [`src/utils/domainPricing.js`](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/utils/domainPricing.js) (Business Adapters), [`src/App.jsx`](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/App.jsx) (App), [`src/api/axios.js`](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/api/axios.js) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell"]
  node_src_main["Main<br/>entrypoint<br/>[main.jsx]"]
  node_src_app["App<br/>router<br/>[App.jsx]"]
  node_src_layout["App Layout<br/>[AppLayout.jsx]"]
  node_src_protected_route["Protected Route<br/>auth gate<br/>[ProtectedRoute.jsx]"]
end

subgraph group_state["State"]
  node_src_auth_context(("Auth Context<br/>session state<br/>[AuthContext.jsx]"))
  node_src_currency_context(("Currency Context<br/>display state"))
  node_src_language_context(("Language Context<br/>locale state"))
  node_src_cookie_context(("Cookie Consent<br/>privacy state"))
  node_src_hooks_socket["Realtime Hooks<br/>websocket hooks"]
end

subgraph group_features["Features"]
  node_src_home_pages["Home Pages<br/>routes<br/>[Home.jsx]"]
  node_src_market_pages["Marketplace<br/>domain routes<br/>[DomainsPage.jsx]"]
  node_src_venture_pages["Ventures<br/>domain routes<br/>[VenturesPage.jsx]"]
  node_src_tech_pages["Technology<br/>domain routes<br/>[CoCreationPage.jsx]"]
  node_src_auction_pages["Auctions<br/>market routes<br/>[AuctionsPage.jsx]"]
  node_src_admin_pages["Admin Ops<br/>ops routes"]
end

subgraph group_data["Data"]
  node_src_api_client["API Client<br/>http client<br/>[axios.js]"]
  node_src_api_services["Feature APIs<br/>service modules<br/>[services.js]"]
  node_src_config_urls["Backend URLs<br/>endpoint config<br/>[urls.js]"]
  node_src_utils_adapters["Business Adapters<br/>data shaping<br/>[domainPricing.js]"]
end

subgraph group_infra["Infra"]
  node_src_i18n["i18n<br/>localization<br/>[i18n.js]"]
  node_src_build_deploy["Build & Deploy<br/>runtime config<br/>[vite.config.js]"]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"wraps"| node_src_layout
node_src_app -->|"guards"| node_src_protected_route
node_src_main -->|"provides"| node_src_auth_context
node_src_main -->|"provides"| node_src_currency_context
node_src_main -->|"provides"| node_src_language_context
node_src_main -->|"provides"| node_src_cookie_context
node_src_main -->|"initializes"| node_src_i18n
node_src_auth_context -->|"controls"| node_src_protected_route
node_src_auth_context -->|"authorizes"| node_src_api_services
node_src_hooks_socket -->|"subscribes via"| node_src_api_client
node_src_api_client -->|"targets"| node_src_config_urls
node_src_api_services -->|"uses"| node_src_api_client
node_src_utils_adapters -->|"shapes"| node_src_api_services
node_src_utils_adapters -->|"formats"| node_src_currency_context
node_src_home_pages -->|"consumes"| node_src_utils_adapters
node_src_market_pages -->|"consumes"| node_src_utils_adapters
node_src_venture_pages -->|"consumes"| node_src_utils_adapters
node_src_tech_pages -->|"consumes"| node_src_utils_adapters
node_src_auction_pages -->|"updates live"| node_src_hooks_socket
node_src_admin_pages -->|"requires"| node_src_protected_route
node_src_admin_pages -->|"queries"| node_src_api_services
node_src_build_deploy -->|"routes to backend"| node_src_api_client
node_src_build_deploy -->|"preserves spa"| node_src_app

click node_src_main "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/main.jsx"
click node_src_app "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/App.jsx"
click node_src_layout "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/components/layout/AppLayout.jsx"
click node_src_protected_route "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/components/auth/ProtectedRoute.jsx"
click node_src_auth_context "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/AuthContext.jsx"
click node_src_currency_context "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/CurrencyContext.jsx"
click node_src_language_context "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/LanguageContext.jsx"
click node_src_cookie_context "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/CookieConsentContext.jsx"
click node_src_hooks_socket "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/hooks/useNotificationSocket.js"
click node_src_api_client "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/api/axios.js"
click node_src_api_services "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/api/services.js"
click node_src_config_urls "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/config/urls.js"
click node_src_utils_adapters "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/utils/domainPricing.js"
click node_src_home_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/Home.jsx"
click node_src_market_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/DomainsPage.jsx"
click node_src_venture_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/VenturesPage.jsx"
click node_src_tech_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/CoCreationPage.jsx"
click node_src_auction_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/AuctionsPage.jsx"
click node_src_admin_pages "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/AdminDashboardPage.jsx"
click node_src_i18n "https://github.com/cobrother-official/cobrother_frontend/blob/main/src/i18n.js"
click node_src_build_deploy "https://github.com/cobrother-official/cobrother_frontend/blob/main/vite.config.js"

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_src_layout,node_src_protected_route toneBlue
class node_src_auth_context,node_src_currency_context,node_src_language_context,node_src_cookie_context,node_src_hooks_socket toneAmber
class node_src_home_pages,node_src_market_pages,node_src_venture_pages,node_src_tech_pages,node_src_auction_pages,node_src_admin_pages toneMint
class node_src_api_client,node_src_api_services,node_src_config_urls,node_src_utils_adapters toneRose
class node_src_i18n,node_src_build_deploy toneIndigo
```

## Components

### Shell

App entry, routing, layout, and global UI framing.

- [Main](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/main.jsx): entrypoint · Bootstraps the React app and global providers. · `src/main.jsx`
- [App](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/App.jsx): router · Top-level route composition and app wiring. · `src/App.jsx`
- [App Layout](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/components/layout/AppLayout.jsx): layout · Shared page shell and profile/regional navigation. · `src/components/layout/AppLayout.jsx`
- [Protected Route](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/components/auth/ProtectedRoute.jsx): auth gate · Guards authenticated or privileged routes. · `src/components/auth/ProtectedRoute.jsx`

### State

Cross-cutting providers, hooks, and client-side session state.

- [Auth Context](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/AuthContext.jsx): session state · Sign-in, session, and permission state. · `src/context/AuthContext.jsx`
- [Currency Context](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/CurrencyContext.jsx): display state · Currency selection and pricing display state. · `src/context/CurrencyContext.jsx`
- [Language Context](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/LanguageContext.jsx): locale state · Localization and language selection state. · `src/context/LanguageContext.jsx`
- [Cookie Consent](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/context/CookieConsentContext.jsx): privacy state · Consent preferences for tracking and cookies. · `src/context/CookieConsentContext.jsx`
- [Realtime Hooks](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/hooks/useNotificationSocket.js): websocket hooks · SockJS/STOMP subscriptions for auctions and notifications. · `src/hooks/useNotificationSocket.js`

### Features

Business-domain screens and their supporting UI.

- [Home Pages](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/Home.jsx): routes · Home, marketing, and discovery screens. · `src/pages/Home.jsx`
- [Marketplace](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/DomainsPage.jsx): domain routes · Domains, storefront, registration, transfer, and verification flows. · `src/pages/DomainsPage.jsx`
- [Ventures](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/VenturesPage.jsx): domain routes · Venture listings, detail, bids, deals, and dashboards. · `src/pages/VenturesPage.jsx`
- [Technology](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/CoCreationPage.jsx): domain routes · Co-creation and software auction experiences. · `src/pages/CoCreationPage.jsx`
- [Auctions](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/AuctionsPage.jsx): market routes · Shared auction hub and category-specific auction pages. · `src/pages/AuctionsPage.jsx`
- [Admin Ops](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/pages/AdminDashboardPage.jsx): ops routes · Admin, operations, analytics, and request handling screens. · `src/pages/AdminDashboardPage.jsx`

### Data

Network boundary, configuration, and shared adapters.

- [API Client](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/api/axios.js): http client · Axios setup and shared request handling. · `src/api/axios.js`
- [Feature APIs](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/api/services.js): service modules · Feature-specific backend service calls. · `src/api/services.js`
- [Backend URLs](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/config/urls.js): endpoint config · Backend origin and environment-specific endpoint resolution. · `src/config/urls.js`
- [Business Adapters](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/utils/domainPricing.js): data shaping · Pricing, visibility, verification, and domain/listing transforms. · `src/utils/domainPricing.js`

### Infra

Build, deploy, localization, and runtime tooling.

- [i18n](https://github.com/cobrother-official/cobrother_frontend/blob/main/src/i18n.js): localization · Translation resources and language utilities. · `src/i18n.js`
- [Build & Deploy](https://github.com/cobrother-official/cobrother_frontend/blob/main/vite.config.js): runtime config · Vite, Vercel, and workflow deployment settings. · `vite.config.js`

## Connections

- Main → App: mounts · Application entry renders the route tree.
- App → App Layout: wraps · Routes are rendered inside the shared shell.
- App → Protected Route: guards · Privileged routes are wrapped with protection.
- Main → Auth Context: provides · Global session state is initialized at app start.
- Main → Currency Context: provides · Currency formatting is app-wide.
- Main → Language Context: provides · Localization state is app-wide.
- Main → Cookie Consent: provides · Consent state is app-wide.
- Main → i18n: initializes · Translation system is loaded on startup.
- Auth Context → Protected Route: controls · Auth state determines route access.
- Auth Context → Feature APIs: authorizes · Authenticated requests use session-aware API calls.
- Realtime Hooks → API Client: subscribes via · Realtime features coordinate with backend transport.
- API Client → Backend URLs: targets · Client base URLs come from environment config.
- Feature APIs → API Client: uses · Feature services build on the shared client.
- Business Adapters → Feature APIs: shapes · Adapters transform backend data for UI use.
- Business Adapters → Currency Context: formats · Business values are displayed in selected currency.
- Home Pages → Business Adapters: consumes · Home discovery sections use derived listing data.
- Marketplace → Business Adapters: consumes · Marketplace screens rely on pricing and verification adapters.
- Ventures → Business Adapters: consumes · Venture flows use listing, deal, and verification helpers.
- Technology → Business Adapters: consumes · Technology and co-creation screens use auction/listing helpers.
- Auctions → Realtime Hooks: updates live · Auction pages receive realtime status changes.
- Admin Ops → Protected Route: requires · Admin and operations views are access controlled.
- Admin Ops → Feature APIs: queries · Dashboards and ops views load backend data.
- Build & Deploy → API Client: routes to backend · Deployment config preserves API/backend separation.
- Build & Deploy → App: preserves spa · Client-side routing is supported in deployment.