How quantum-one-dlt/onyx-one works
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: layout.tsx App shell · supabase.ts Supabase core · site-header.tsx Site chrome · middleware.ts Middleware
Components 29
App routes
Next.js App Router pages, route handlers, and route-local features
- App shell · Global app layout and root providers
app/layout.tsx - Home · Root landing page and entry point
app/page.tsx - Auth · Sign-in, callback, OAuth, confirmation, and signout flows
app/auth/page.tsx - Server auth · Parallel auth flow implemented with server actions
app/auth-server-action/page.tsx - Dashboard · Authenticated dashboard shell and shared layout
app/dashboard/layout.tsx - Members · Dashboard member management screens and actions
app/dashboard/members/page.tsx - Todo · Dashboard todo management screens and actions
app/dashboard/todo/page.tsx - Account · User account and profile editing area
app/account/page.tsx - Contact · Contact form surface backed by email sending
app/contact/page.tsx - Docs · MDX-backed documentation and policy/content pages
app/docs/dfi1/v1/factorycontract/page.mdx - Content pages · Public informational pages such as about, privacy, terms, onboarding, and demos
app/about/page.tsx - Countries · Country detail routes and SSR country variant
app/countries/[id]/page.tsx - Playground · Model and preset playground UI
app/playground/page.tsx - Music · Media-style playlist and album browsing UI
app/music/page.tsx - Token sale · Token sale and pricing surface
app/tokensale/pricing.module.css
Shared UI
Cross-cutting components, forms, providers, and design system primitives
- UI kit · Shadcn-style reusable primitives for dialogs, forms, tables, and inputs
components/ui/button.tsx - Site chrome · Header, footer, navigation, sidebar, theme, and onboarding shell components
components/site-header.tsx - Forms · Reusable form wrappers, steps, and feature forms
components/forms/formwrapper.tsx - Query provider · React Query client provider for client-side data flows
components/react-query-client-provider.tsx - Theme · Global theme toggle/provider layer
components/theme-provider.tsx - Chain context · Application-specific chain/web3 context wiring
app/ZetachainContext.tsx
Backend
Supabase, queries, middleware, and server-side utilities
- Supabase core · Primary Supabase client, server, browser, and auth admin helpers
lib/supabase.ts - Middleware · Session-preserving middleware and SSR auth boundary
middleware.ts - Queries · Reusable lookups such as country and profile queries
queries/profile-by-user-id.tsx - Email API · Send-email route and shared email sender
app/api/send/route.ts
Web3
Wallet, chain, and token-sale related surfaces
- Wallet UI · Connect buttons, wallet options, and transaction forms
components/connect-button.tsx - Tx forms · Reusable transaction and ABI-driven form helpers
components/forms/send-transaction.tsx - Playground data · Model/preset datasets and interactive playground controls
app/playground/components/model-selector.tsx - Allocation UI · Token allocation view used by the DAFI/token sale surface
app/dafitoken/components/token-allocation.tsx
Connections 25
- 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