Frontend Structure

Understanding the Ryva frontend project organization and architecture

Overview

The Ryva frontend is built with Next.js 16 using the App Router, React 19, TypeScript, and Tailwind CSS. The codebase follows a feature-based modular architecture with clear separation of concerns.

Technology Stack

Core Framework

• Next.js 16.1.1 - React framework with App Router
• React 19.2.3 - UI library with React Compiler enabled
• TypeScript 5.9 - Type safety and developer experience
• Tailwind CSS 4.1 - Utility-first CSS framework

State & Data

• TanStack Query 5.90 - Server state management
• Zustand 5.0 - Client state management
• React Hook Form 7.70 - Form state and validation
• Zod 4.3 - Schema validation

UI & Styling

• Radix UI - Headless component primitives
• Class Variance Authority - Component variant management
• Lucide React - Icon library
• Motion 12 - Animation library
• Sonner - Toast notifications

Backend & Services

• Supabase - Authentication and database client
• Stripe - Payment processing
• Sanity - Content management
• Sentry - Error tracking and monitoring

Directory Structure

src/
├── app/                    # Next.js App Router pages
│   ├── (auth)/            # Authentication routes (login, signup, etc.)
│   ├── (dashbord)/        # Protected dashboard routes
│   ├── (marketing)/       # Public marketing pages
│   ├── (admin)/           # Admin panel routes
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Homepage
│
├── components/            # Shared React components
│   ├── ui/               # Base UI components (shadcn/ui based)
│   ├── app-sidebar.tsx   # Application sidebar
│   ├── app-breadcrumb.tsx # Breadcrumb navigation
│   ├── nav-main.tsx      # Main navigation
│   ├── nav-user.tsx      # User navigation menu
│   └── team-switcher.tsx # Organization switcher
│
├── modules/               # Feature modules
│   ├── auth/             # Authentication module
│   │   ├── components/   # Auth-specific components
│   │   ├── hooks/        # Auth API hooks
│   │   └── types/        # Auth type definitions
│   ├── billing/          # Billing and payments
│   ├── blog/             # Blog functionality
│   ├── organizations/    # Organization management
│   └── waitlist/         # Waitlist features
│
├── lib/                   # Shared utilities and configuration
│   ├── api/              # API client and types
│   │   ├── client.ts     # HTTP client wrapper
│   │   └── types.ts      # API response types
│   ├── supabase/         # Supabase client utilities
│   ├── stripe/           # Stripe integration
│   ├── query-client.ts   # TanStack Query configuration
│   ├── providers.tsx     # React context providers
│   ├── utils.ts          # Utility functions (cn, etc.)
│   ├── config.ts         # App configuration
│   └── metadata.ts       # SEO metadata helpers
│
├── stores/                # Zustand state stores
│   ├── auth.ts           # Auth state (session user)
│   └── waitlist.ts       # Waitlist state (persisted)
│
├── contexts/              # React contexts
│   └── organization-context.tsx # Active organization context
│
├── hooks/                 # Custom React hooks
│   └── use-mobile.ts     # Responsive breakpoint hook
│
├── sanity/                # Sanity CMS configuration
│   ├── client.ts         # Sanity client setup
│   └── schemas/          # Content schemas
│
├── styles/                # Global styles
│   └── globals.css       # Tailwind and global CSS
│
└── instrumentation.ts     # Observability setup (Sentry)

Route Organization

Next.js App Router uses route groups for logical organization:

(auth) - Authentication Routes

Unauthenticated routes for login, signup, password reset, and onboarding.

• /login - Sign in page
• /signup - User registration
• /forgot-password - Password recovery
• /reset-password - Password reset form
• /onboarding - New user onboarding
• /auth/callback - OAuth callback handler

(dashbord) - Protected Dashboard

Authenticated application routes requiring login.

• /app - Main dashboard
• /app/projects - Project management
• /app/invitations - Pending invitations
• /app/settings/* - User and org settings
• /app/billing/* - Subscription management
• /app/checkout - Payment checkout

(marketing) - Public Pages

Public-facing marketing and content pages.

• / - Homepage
• /blog - Blog listing
• /blog/[slug] - Blog post
• /docs - Documentation
• /docs/[category]/[slug] - Doc page
• /privacy - Privacy policy
• /terms - Terms of service

(admin) - Admin Panel

Administrative interface (Sanity Studio).

• /admin - Sanity Studio CMS

Module Architecture

Each feature module follows a consistent structure:

modules/
└── auth/
    ├── components/          # Feature-specific components
    │   ├── login-form.tsx
    │   └── onboarding-flow.tsx
    ├── hooks/              # API hooks and mutations
    │   └── use-auth-api.ts
    ├── types/              # TypeScript types
    │   └── index.ts
    └── index.ts            # Public exports

Modules are self-contained and export their public API through index.ts. This prevents tight coupling and makes refactoring easier.

Key Conventions

File Naming

• Components: kebab-case.tsx (e.g., team-switcher.tsx)
• Hooks: use-*.ts (e.g., use-auth-api.ts)
• Types: types.ts or index.ts in /types folder
• Pages: Next.js conventions (page.tsx, layout.tsx)

Component Organization

Rule of thumb: If a component is used in only one module, it lives in that module’s components/ folder. If it’s shared across features, it goes in src/components/.

Import Aliases

The project uses @/ as the root import alias:

import { Button } from '@/components/ui/button'
import { useUser } from '@/modules/auth/hooks/use-auth-api'
import { cn } from '@/lib/utils'

Configuration Files

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "vitest run",
    "test:e2e": "playwright test",
    "lint": "eslint",
    "type-check": "tsc --noEmit"
  }
}

next.config.js

Configuration for MDX, image optimization, environment variables, and Sentry.

tailwind.config.ts

Tailwind CSS configuration with custom theme, animations, and plugins.

tsconfig.json

TypeScript configuration with strict mode and path aliases.

Build & Development

# Development server
pnpm dev

# Production build
pnpm build

# Type checking
pnpm type-check

# Run tests
pnpm test           # Unit tests (Vitest)
pnpm test:e2e       # E2E tests (Playwright)

# Code quality
pnpm lint
pnpm format

The project requires Node.js >= 20.0.0 and pnpm >= 9.0.0.

Next Steps

Component Patterns

Learn about component architecture and UI patterns

State Management

Understand TanStack Query and Zustand patterns