01 - Architecture

Overview

Wavic WebApp is a modern React application built with Next.js 15 using the App Router pattern. It serves as the frontend for the Wavic music collaboration platform, communicating with a NestJS 11 backend API.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         WAVIC WEBAPP                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐            │
│   │   Pages     │    │  Layouts    │    │ Components  │            │
│   │ (App Router)│◄───│ (6 options) │◄───│ (RizzUI +   │            │
│   │             │    │             │    │  Custom)    │            │
│   └──────┬──────┘    └─────────────┘    └─────────────┘            │
│          │                                                          │
│   ┌──────▼──────┐    ┌─────────────┐    ┌─────────────┐            │
│   │   Server    │    │  Contexts   │    │    Hooks    │            │
│   │  Actions    │    │ (Wave, Auth,│    │ (30+ custom)│            │
│   │             │    │  Dropzone)  │    │             │            │
│   └──────┬──────┘    └─────────────┘    └─────────────┘            │
│          │                                                          │
└──────────┼──────────────────────────────────────────────────────────┘
           │
           ▼
    ┌─────────────┐
    │  WAVIC API  │
    │  (NestJS)   │
    │  Port 8080  │
    └─────────────┘

Technology Stack

Core Framework

Technology	Version	Purpose
Next.js	15.5.12	React framework with App Router
React	19.1.0	UI library
TypeScript	5.7+	Type-safe JavaScript
Turbopack	(built-in)	Fast development builds

Styling & UI

Technology	Version	Purpose
Tailwind CSS	4.1.18	Utility-first CSS (CSS-first config)
RizzUI	2.1.0	Pre-built component library
Framer Motion	12.33.0	Animations and transitions
react-icons	5.3.0	Icon library

State Management

Technology	Version	Purpose
React Context	(built-in)	Component-tree state
Jotai	2.17.0	Atomic state management
next-auth	4.24.13	Authentication state

Data & Forms

Technology	Version	Purpose
React Hook Form	7.53.0	Form state management
Zod	3.23.8	Schema validation
@tanstack/react-table	8.20.5	Data tables

Audio & Media

Technology	Version	Purpose
WaveSurfer.js	7.6.0	Audio waveform visualization
react-player	2.16.0	Media playback
Swiper	11.1.14	Image carousels

Integrations

Technology	Version	Purpose
Stripe	8.0.0	Payment processing
Three.js	0.173.0	3D graphics (CD animation)
nodemailer	8.0.0	Email sending

Design Patterns

1. App Router Pattern (Next.js 15)

The application uses Next.js App Router with route groups:

src/app/
├── (hydrogen)/          # Main authenticated routes
│   ├── artist/          # Artist space pages
│   ├── project/         # Project pages
│   ├── wave/            # Track/waveform pages
│   └── layout.tsx       # Layout with sidebar
├── (other-pages)/       # Secondary pages
├── api/                 # API routes
└── layout.tsx           # Root layout

2. Server Actions Pattern

API calls are made through Server Actions (React Server Components):

// src/server-actions/artist/actions.tsx
'use server';

export const getArtists = async (session: any) => {
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_BASE_URL}/artist`,
    {
      headers: { Authorization: `Bearer ${session?.token}` },
    }
  );
  return response.json();
};

3. Multi-Layout System

The app supports 6 different layout configurations:

Layout	Description
Beryllium	Default - Clean header, minimal sidebar
Hydrogen	Full sidebar layout
Helium	Compact navigation
Lithium	Wide content area
Boron	Minimal chrome
Carbon	Alternative style

4. Context-Based State

Major features use dedicated React Contexts:

// Key contexts:
WaveContext       → Audio player, track, waveform state
NotificationContext → Real-time notifications
DropZoneContext   → File upload state
LoadingContext    → Global loading states
NavigatorContext  → Navigation state

5. Component Composition

Components follow atomic design principles:

components/
├── ui/              # Atoms (buttons, inputs)
├── cards/           # Molecules (track cards)
├── headers/         # Organisms (page headers)
├── modal/           # Modal dialogs
└── skeletons/       # Loading states

Data Flow

┌──────────┐    ┌─────────────┐    ┌──────────────┐    ┌──────────┐
│  User    │───►│  Component  │───►│   Server     │───►│   API    │
│  Action  │    │  (Client)   │    │   Action     │    │ (NestJS) │
└──────────┘    └─────────────┘    └──────────────┘    └──────────┘
                       │                  │                   │
                       ▼                  ▼                   ▼
                ┌─────────────┐    ┌──────────────┐    ┌──────────┐
                │   Context   │◄───│   Response   │◄───│  MongoDB │
                │   Update    │    │              │    │          │
                └─────────────┘    └──────────────┘    └──────────┘

Key Architectural Decisions

1. Why App Router over Pages Router?

• Better performance with React Server Components
• Simplified data fetching with Server Actions
• Improved layout nesting capabilities

2. Why Server Actions over API Routes?

• Reduced client-side bundle
• Automatic request deduplication
• Type-safe end-to-end

3. Why RizzUI?

• Pre-built accessible components
• Tailwind-native styling
• Consistent design language

4. Why Multi-Layout System?

• A/B testing different UI approaches
• User preference customization
• Incremental UI updates

Environment Configuration

The app uses @t3-oss/env-nextjs for type-safe environment variables:

// src/env.mjs
export const env = createEnv({
  server: {
    NODE_ENV: z.enum(['development', 'test', 'production']),
    NEXTAUTH_SECRET: z.string(),
    NEXTAUTH_URL: z.string().url(),
    GOOGLE_CLIENT_ID: z.string().optional(),
    GOOGLE_CLIENT_SECRET: z.string().optional(),
  },
  client: {
    NEXT_PUBLIC_APP_NAME: z.string().optional(),
  },
});

Performance Optimizations

1. Turbopack: Development server uses Turbo for fast HMR
2. Image Optimization: Next.js Image component with remote patterns
3. Skeleton Loading: All data-dependent views show loading skeletons
4. Lazy Loading: Components loaded on-demand where appropriate

---

Tech Stack Assessment

✅ Strong Choices

Technology	Why It Works
Next.js 15 + App Router	Industry standard, great SEO, server components, excellent DX
TypeScript 5.6	Type safety critical for a collaborative app
Tailwind CSS	Fast UI development, consistent design system
Jotai	Lightweight, atomic state - perfect for audio player state
WaveSurfer.js	Best-in-class waveform library, actively maintained
NextAuth.js	Handles OAuth/credentials well, good security defaults
Stripe	Gold standard for payments

⚠️ Considerations

Area	Current	Consideration
RizzUI	v2.1.0	Stable v2 with Tailwind v4 support. Breaking API changes from v1 resolved
Turbopack	Dev mode	Stable in Next.js 15 for development builds
No Testing	None found	Critical gap - add Vitest + Playwright before scaling
No Monorepo	Separate repos	Consider Turborepo if API/webapp need shared types
Audio Processing	Client-side only	For enterprise, may need server-side transcoding (FFmpeg)

Enterprise Readiness Gaps

Need	Recommended Solution
Observability	Sentry (errors), Application Insights or PostHog
Feature Flags	LaunchDarkly or Azure App Configuration
CDN for Audio	Azure CDN or CloudFront
Real-time Collab	Azure SignalR or Socket.io for live cursors/presence
Background Jobs	Azure Functions or Inngest for async processing

---

Cloud Infrastructure

Platform: Microsoft Azure

Component	Azure Service	Purpose
API (NestJS)	Container Apps	Serverless containers with auto-scale
Database	Cosmos DB (MongoDB API)	Document database, seamless MongoDB migration
File Storage	Blob Storage	Audio files, attachments, images
CDN	Azure CDN	Global audio streaming delivery
Auth	Entra ID B2C (future)	Enterprise SSO when needed
Monitoring	Application Insights	APM, logs, metrics, tracing
CI/CD	GitHub Actions	Source control and deployments
Secrets	Key Vault	API keys, connection strings

Cost Estimates

Scale	Monthly Estimate	Notes
Dev/Test	~$50-80	Free tiers where available
Production (100 users)	~$150-250	Container Apps + Cosmos DB + Blob
Scale (1000+ users)	~$500-800	Auto-scaling, reserved capacity

Deployment Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AZURE                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│   │   Azure CDN  │     │  Container   │     │  Cosmos DB   │   │
│   │  (Audio/     │     │    Apps      │     │  (MongoDB)   │   │
│   │   Static)    │     │  (NestJS)    │     │              │   │
│   └──────┬───────┘     └──────┬───────┘     └──────┬───────┘   │
│          │                    │                    │           │
│          │             ┌──────▼───────┐            │           │
│          │             │    Blob      │            │           │
│          └────────────►│   Storage    │◄───────────┘           │
│                        │  (Audio/     │                        │
│                        │   Files)     │                        │
│                        └──────────────┘                        │
│                                                                 │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│   │  App Insights│     │  Key Vault   │     │ Azure DevOps │   │
│   │  (Monitoring)│     │  (Secrets)   │     │  (CI/CD)     │   │
│   └──────────────┘     └──────────────┘     └──────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Migration Path

1. Phase 1: Deploy API to Azure Container Apps
2. Phase 2: Set up Cosmos DB (MongoDB API), migrate data
3. Phase 3: Configure Azure Blob Storage for audio files
4. Phase 4: Add Azure CDN for global audio delivery
5. Phase 5: Implement Application Insights for observability