# quantum-one-dlt/onyx-one architecture

> Architecture diagram of the GitHub repository quantum-one-dlt/onyx-one, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantum-one-dlt/onyx-one
- Repository: https://github.com/quantum-one-dlt/onyx-one

## Overview

1. **Overall shape**
   - This is a **Next.js 14 App Router** application written in **TypeScript**. It mixes public marketing/content pages, authenticated user areas, a role-based admin dashboard, and several web3-oriented demo/product surfaces.
   - The repo is organized around the `app/` directory for routes and route handlers, with shared UI, auth, Supabase, and web3 utilities living outside the route tree.

2. **Primary runtime boundaries**
   - **Server-side boundary:** Next route handlers, server components, middleware, and server actions handle auth callbacks, form submissions, email sending, and protected data access.
   - **Client-side boundary:** interactive UI lives in `components/` and route-local `components/` folders, using React Hook Form, Shadcn UI, and client-side wallet/auth interactions.
   - The architecture is intentionally split between **SSR/authenticated server flows** and **interactive client flows**.

3. **Supabase is the core backend**
   - Supabase is the main persistence and auth layer: **SSR authentication**, Postgres access, browser/server clients, and typed query helpers are all present.
   - Key support files live in `lib/supabase.ts`, `utils/supabase-browser.ts`, `utils/supabase-server.ts`, `utils/supabase/middleware.ts`, `utils/typed-supabase-client.tsx`, and `utils/supa-auth-admin.tsx`.
   - The README and file layout indicate the app expects matching Supabase schema/types and uses middleware to keep sessions valid across requests.

4. **Auth system and session routing**
   - Auth is implemented through dedicated routes under `app/auth/`:
     - sign-in / auth forms
     - OAuth callback handling
     - Google OAuth route
     - confirmation and signout routes
   - There is also a parallel `app/auth-server-action/` area showing a **server-action-based auth flow**.
   - The `middleware.ts` file is an important boundary for protecting pages and preserving SSR auth state.

5. **Protected dashboard and RBAC**
   - `app/dashboard/` is the main authenticated area, with a shared dashboard layout and nested modules for **members** and **todo**.
   - The dashboard includes navigation, sidebar toggles, search, user menu, sign-out, and responsive mobile navigation.
   - The README explicitly calls out **RBAC**, so access control is a first-class architectural concern, likely enforced at the route/query level in addition to UI gating.

6. **CRUD feature modules**
   - The dashboard’s `members` and `todo` sections each have their own:
     - route page
     - local components for tables, forms, dialogs, search
     - actions folder for mutations
   - This indicates a standard pattern: **page → feature components → server actions / queries → Supabase**.
   - `queries/` contains reusable data lookups such as `country-by-id` and `profile-by-user-id`, which suggests shared query logic outside the route tree.

7. **Web3 / DApp integration layer**
   - The repo is not just a normal SaaS app; it includes a DApp stack built around **TanStack React Query**, **Wagmi SSR**, and **Web3Modal**.
   - Evidence includes wallet/connect-related components, transaction helpers, a token sale page, token allocation UI, and generic forms for sending transactions.
   - The runtime boundary here is important: wallet state and on-chain interaction are likely client-heavy, while SSR providers and React Query cache hydration keep the wallet experience stable across page loads.

8. **Shared UI and design system**
   - `components/ui/` contains the Shadcn-style primitive set: dialog, sheet, tabs, form controls, toasts, tables, etc.
   - App-level shared components such as headers, sidebars, theme toggle/provider, mobile nav, footer, and onboarding progress are centralized in `components/`.
   - Route-local components then compose these primitives into feature-specific screens.

9. **Forms and validation**
   - Form handling is a major subsystem: `components/forms/` contains reusable wrappers, steps, profile/contact forms, transaction forms, and form action helpers.
   - The README mentions both **Zod** and **Yup**, and the file tree shows React Hook Form integration.
   - This suggests a deliberate separation between reusable form infrastructure and feature-specific form screens.

10. **Email and API surface**
   - There is a small API surface under `app/api/send/route.ts`, and a shared `utils/send-email.ts`.
   - This likely supports contact or transactional email via **Resend**, which is called out in the README.
   - The email template lives in `components/email-template.tsx`, making email rendering part of the shared UI layer rather than a separate service.

11. **Content, docs, and static pages**
   - The app includes many non-interactive routes: about, privacy, terms, return policy, research room, docs pages, onboarding, profile, private, and others.
   - Several of these are MDX-backed with route-specific layouts, which means the app supports **documentation/content rendering** alongside dynamic app screens.
   - `mdx-components.tsx`, `config/docs.ts`, and `app/docs/...` are the main content architecture hooks.

12. **Media, marketing, and SEO infrastructure**
   - The repo includes `app/opengraph-image.tsx`, `app/sitemap.xml.js`, `public/robots.txt`, and a service worker, indicating attention to share cards, indexing, and possibly PWA behavior.
   - There are also marketing-style pages like music, playground, tokensale, and country demos that likely showcase different UI/interaction patterns within the same app shell.

13. **Cross-cutting providers and app shell**
   - Global providers live in `app/layout.tsx`, `components/theme-provider.tsx`, `components/react-query-client-provider.tsx`, and `app/ZetachainContext.tsx`.
   - These providers establish the global runtime: theme, query cache, and chain/web3 context.
   - The app shell is therefore the main integration point for auth state, wallet state, and UI theme.

14. **Most important architecture diagram takeaway**
   - The repo is best drawn as a **single Next.js monorepo-style app** with three big zones:
     - **public/content routes**
     - **authenticated Supabase-backed app/dashboard**
     - **web3-enabled DApp surfaces**
   - The shared backbone is: **Next.js App Router + Supabase SSR auth + shared UI/forms + web3 providers + small API/email endpoints**.

Main entry points: [`app/layout.tsx`](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/layout.tsx) (App shell), [`lib/supabase.ts`](https://github.com/quantum-one-dlt/onyx-one/blob/main/lib/supabase.ts) (Supabase core), [`components/site-header.tsx`](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/site-header.tsx) (Site chrome), [`middleware.ts`](https://github.com/quantum-one-dlt/onyx-one/blob/main/middleware.ts) (Middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_home_page["Home<br/>marketing page<br/>[page.tsx]"]
  node_auth_routes["Auth<br/>[page.tsx]"]
  node_server_auth["Server auth<br/>server-action auth<br/>[page.tsx]"]
  node_dashboard_shell["Dashboard<br/>protected area<br/>[layout.tsx]"]
  node_members_feature["Members<br/>crud module<br/>[page.tsx]"]
  node_todo_feature["Todo<br/>crud module<br/>[page.tsx]"]
  node_account_page["Account<br/>profile page<br/>[page.tsx]"]
  node_contact_page["Contact<br/>form page<br/>[page.tsx]"]
  node_docs_content["Docs<br/>[page.mdx]"]
  node_content_pages["Content pages<br/>static routes<br/>[page.tsx]"]
  node_country_pages["Countries<br/>data pages<br/>[page.tsx]"]
  node_playground_page["Playground<br/>interactive page<br/>[page.tsx]"]
  node_music_page["Music<br/>media page<br/>[page.tsx]"]
  node_tokensale_page["Token sale<br/>web3 page<br/>[pricing.module.css]"]
end

subgraph group_shared["Shared UI"]
  node_ui_kit["UI kit<br/>design system<br/>[button.tsx]"]
  node_site_chrome["Site chrome<br/>shared chrome<br/>[site-header.tsx]"]
  node_form_system["Forms<br/>form infra<br/>[formwrapper.tsx]"]
  node_react_query_provider(("Query provider"))
  node_theme_provider(("Theme<br/>provider<br/>[theme-provider.tsx]"))
  node_app_context(("Chain context<br/>provider"))
end

subgraph group_backend["Backend"]
  node_supabase_core["Supabase core<br/>backend core<br/>[supabase.ts]"]
  node_supabase_middleware["Middleware<br/>[middleware.ts]"]
  node_query_helpers["Queries<br/>data access"]
  node_email_api["Email API<br/>api endpoint<br/>[route.ts]"]
end

subgraph group_web3["Web3"]
  node_web3_components["Wallet UI<br/>web3 ui<br/>[connect-button.tsx]"]
  node_web3_forms["Tx forms<br/>web3 forms"]
  node_web3_playground["Playground data<br/>web3 data<br/>[model-selector.tsx]"]
  node_token_allocation["Allocation UI<br/>token sale ui"]
end

node_app_layout -->|"wraps"| node_theme_provider
node_app_layout -->|"wraps"| node_react_query_provider
node_app_layout -->|"wraps"| node_app_context
node_app_layout -->|"composes"| node_site_chrome
node_app_layout -->|"relies on"| node_supabase_middleware
node_home_page -->|"uses"| node_site_chrome
node_auth_routes -->|"authenticates with"| node_supabase_core
node_server_auth -->|"authenticates with"| node_supabase_core
node_supabase_middleware -->|"protects"| node_supabase_core
node_dashboard_shell -->|"guards"| node_supabase_middleware
node_dashboard_shell -->|"uses"| node_site_chrome
node_members_feature -->|"persists to"| node_supabase_core
node_members_feature -->|"uses"| node_form_system
node_todo_feature -->|"persists to"| node_supabase_core
node_todo_feature -->|"uses"| node_form_system
node_account_page -->|"reads/writes"| node_supabase_core
node_contact_page -->|"submits to"| node_email_api
node_docs_content -->|"uses"| node_site_chrome
node_country_pages -->|"loads"| node_query_helpers
node_playground_page -->|"renders"| node_web3_playground
node_music_page -->|"uses"| node_site_chrome
node_tokensale_page -->|"uses"| node_web3_components
node_tokensale_page -->|"renders"| node_token_allocation
node_web3_components -->|"composes"| node_web3_forms
node_web3_forms -->|"depends on"| node_app_context

click node_app_layout "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/layout.tsx"
click node_home_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/page.tsx"
click node_auth_routes "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/auth/page.tsx"
click node_server_auth "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/auth-server-action/page.tsx"
click node_dashboard_shell "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/layout.tsx"
click node_members_feature "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/members/page.tsx"
click node_todo_feature "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/todo/page.tsx"
click node_account_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/account/page.tsx"
click node_contact_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/contact/page.tsx"
click node_docs_content "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/docs/dfi1/v1/factorycontract/page.mdx"
click node_content_pages "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/about/page.tsx"
click node_country_pages "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/countries/[id]/page.tsx"
click node_playground_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/playground/page.tsx"
click node_music_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/music/page.tsx"
click node_tokensale_page "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/tokensale/pricing.module.css"
click node_ui_kit "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/ui/button.tsx"
click node_site_chrome "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/site-header.tsx"
click node_form_system "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/forms/formwrapper.tsx"
click node_react_query_provider "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/react-query-client-provider.tsx"
click node_theme_provider "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/theme-provider.tsx"
click node_app_context "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/ZetachainContext.tsx"
click node_supabase_core "https://github.com/quantum-one-dlt/onyx-one/blob/main/lib/supabase.ts"
click node_supabase_middleware "https://github.com/quantum-one-dlt/onyx-one/blob/main/middleware.ts"
click node_query_helpers "https://github.com/quantum-one-dlt/onyx-one/blob/main/queries/profile-by-user-id.tsx"
click node_email_api "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/api/send/route.ts"
click node_web3_components "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/connect-button.tsx"
click node_web3_forms "https://github.com/quantum-one-dlt/onyx-one/blob/main/components/forms/send-transaction.tsx"
click node_web3_playground "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/playground/components/model-selector.tsx"
click node_token_allocation "https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dafitoken/components/token-allocation.tsx"

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_app_layout,node_home_page,node_auth_routes,node_server_auth,node_dashboard_shell,node_members_feature,node_todo_feature,node_account_page,node_contact_page,node_docs_content,node_content_pages,node_country_pages,node_playground_page,node_music_page,node_tokensale_page toneBlue
class node_ui_kit,node_site_chrome,node_form_system,node_react_query_provider,node_theme_provider,node_app_context toneAmber
class node_supabase_core,node_supabase_middleware,node_query_helpers,node_email_api toneMint
class node_web3_components,node_web3_forms,node_web3_playground,node_token_allocation toneRose
```

## Components

### App routes

Next.js App Router pages, route handlers, and route-local features

- [App shell](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/layout.tsx): next layout · Global app layout and root providers · `app/layout.tsx`
- [Home](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/page.tsx): marketing page · Root landing page and entry point · `app/page.tsx`
- [Auth](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/auth/page.tsx): auth routes · Sign-in, callback, OAuth, confirmation, and signout flows · `app/auth/page.tsx`
- [Server auth](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/auth-server-action/page.tsx): server-action auth · Parallel auth flow implemented with server actions · `app/auth-server-action/page.tsx`
- [Dashboard](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/layout.tsx): protected area · Authenticated dashboard shell and shared layout · `app/dashboard/layout.tsx`
- [Members](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/members/page.tsx): crud module · Dashboard member management screens and actions · `app/dashboard/members/page.tsx`
- [Todo](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dashboard/todo/page.tsx): crud module · Dashboard todo management screens and actions · `app/dashboard/todo/page.tsx`
- [Account](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/account/page.tsx): profile page · User account and profile editing area · `app/account/page.tsx`
- [Contact](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/contact/page.tsx): form page · Contact form surface backed by email sending · `app/contact/page.tsx`
- [Docs](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/docs/dfi1/v1/factorycontract/page.mdx): mdx docs · MDX-backed documentation and policy/content pages · `app/docs/dfi1/v1/factorycontract/page.mdx`
- [Content pages](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/about/page.tsx): static routes · Public informational pages such as about, privacy, terms, onboarding, and demos · `app/about/page.tsx`
- [Countries](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/countries/[id]/page.tsx): data pages · Country detail routes and SSR country variant · `app/countries/[id]/page.tsx`
- [Playground](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/playground/page.tsx): interactive page · Model and preset playground UI · `app/playground/page.tsx`
- [Music](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/music/page.tsx): media page · Media-style playlist and album browsing UI · `app/music/page.tsx`
- [Token sale](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/tokensale/pricing.module.css): web3 page · Token sale and pricing surface · `app/tokensale/pricing.module.css`

### Shared UI

Cross-cutting components, forms, providers, and design system primitives

- [UI kit](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/ui/button.tsx): design system · Shadcn-style reusable primitives for dialogs, forms, tables, and inputs · `components/ui/button.tsx`
- [Site chrome](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/site-header.tsx): shared chrome · Header, footer, navigation, sidebar, theme, and onboarding shell components · `components/site-header.tsx`
- [Forms](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/forms/formwrapper.tsx): form infra · Reusable form wrappers, steps, and feature forms · `components/forms/formwrapper.tsx`
- [Query provider](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/react-query-client-provider.tsx): provider · React Query client provider for client-side data flows · `components/react-query-client-provider.tsx`
- [Theme](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/theme-provider.tsx): provider · Global theme toggle/provider layer · `components/theme-provider.tsx`
- [Chain context](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/ZetachainContext.tsx): provider · Application-specific chain/web3 context wiring · `app/ZetachainContext.tsx`

### Backend

Supabase, queries, middleware, and server-side utilities

- [Supabase core](https://github.com/quantum-one-dlt/onyx-one/blob/main/lib/supabase.ts): backend core · Primary Supabase client, server, browser, and auth admin helpers · `lib/supabase.ts`
- [Middleware](https://github.com/quantum-one-dlt/onyx-one/blob/main/middleware.ts): auth middleware · Session-preserving middleware and SSR auth boundary · `middleware.ts`
- [Queries](https://github.com/quantum-one-dlt/onyx-one/blob/main/queries/profile-by-user-id.tsx): data access · Reusable lookups such as country and profile queries · `queries/profile-by-user-id.tsx`
- [Email API](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/api/send/route.ts): api endpoint · Send-email route and shared email sender · `app/api/send/route.ts`

### Web3

Wallet, chain, and token-sale related surfaces

- [Wallet UI](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/connect-button.tsx): web3 ui · Connect buttons, wallet options, and transaction forms · `components/connect-button.tsx`
- [Tx forms](https://github.com/quantum-one-dlt/onyx-one/blob/main/components/forms/send-transaction.tsx): web3 forms · Reusable transaction and ABI-driven form helpers · `components/forms/send-transaction.tsx`
- [Playground data](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/playground/components/model-selector.tsx): web3 data · Model/preset datasets and interactive playground controls · `app/playground/components/model-selector.tsx`
- [Allocation UI](https://github.com/quantum-one-dlt/onyx-one/blob/main/app/dafitoken/components/token-allocation.tsx): token sale ui · Token allocation view used by the DAFI/token sale surface · `app/dafitoken/components/token-allocation.tsx`

## Connections

- App shell → Theme: wraps · Root layout installs theme provider
- App shell → Query provider: wraps · Root layout installs React Query cache
- App shell → Chain context: wraps · Root layout provides chain/web3 context
- App shell → Site chrome: composes · Global shell pulls in shared navigation and footer
- App shell → Middleware: relies on · App runtime depends on session-preserving middleware
- Home → Site chrome: uses · Landing page composes shared chrome
- Auth → Supabase core: authenticates with · Auth flows use Supabase clients and helpers
- Server auth → Supabase core: authenticates with · Server-action auth flow uses Supabase utilities
- Middleware → Supabase core: protects · Middleware maintains SSR auth/session state
- Dashboard → Middleware: guards · Protected dashboard depends on middleware-based access control
- Dashboard → Site chrome: uses · Dashboard layout renders shared shell components
- Members → Supabase core: persists to · Member CRUD uses Supabase-backed data access
- Members → Forms: uses · Member create/edit screens use reusable form infrastructure
- Todo → Supabase core: persists to · Todo CRUD uses Supabase-backed data access
- Todo → Forms: uses · Todo screens use reusable form infrastructure
- Account → Supabase core: reads/writes · Account editing is tied to Supabase auth/profile data
- Contact → Email API: submits to · Contact form sends mail through the shared API surface
- Docs → Site chrome: uses · Docs pages render inside route-local layouts and shared chrome
- Countries → Queries: loads · Country routes are backed by reusable query helpers
- Playground → Playground data: renders · Playground page composes interactive selectors and presets
- Music → Site chrome: uses · Media-style page reuses shared app chrome
- Token sale → Wallet UI: uses · Token sale surface uses wallet/connect UI
- Token sale → Allocation UI: renders · Pricing/token sale page includes allocation UI
- Wallet UI → Tx forms: composes · Wallet UI depends on transaction form helpers
- Tx forms → Chain context: depends on · Transaction flows rely on chain context and providers
