Frontend Overview¶

The Carbon Connect frontend is a Next.js 14 application using the App Router, React 18, TypeScript, and Tailwind CSS with shadcn/ui components.

Tech Stack¶

Technology	Version	Purpose
Next.js	14+	React framework with App Router
React	18+	UI library
TypeScript	5+	Type safety (strict mode)
Tailwind CSS	3+	Utility-first CSS framework
shadcn/ui	Latest	Component library (Radix primitives)
React Query	5 (TanStack Query)	Server state management
Framer Motion	Latest	Animations and transitions

Project Structure¶

frontend/
    src/
        app/                    # Next.js App Router pages
            layout.tsx          # Root layout (providers, fonts)
            page.tsx            # Landing page (/)
            providers.tsx       # React Query + theme providers
            globals.css         # Global styles (Tailwind directives)
            login/              # Login page (/login)
            register/           # Registration page (/register)
            verify-email/       # Email verification (/verify-email)
            dashboard/          # Authenticated dashboard (/dashboard/*)
                layout.tsx      # Dashboard shell (sidebar, header)
                page.tsx        # Dashboard home (/dashboard)
                grants/         # Grant search and detail (/dashboard/grants)
                companies/      # Company management (/dashboard/companies)
                matches/        # Match results (/dashboard/matches)
                applications/   # Application tracking (/dashboard/applications)
                carbon-profile/ # Carbon profile form (/dashboard/carbon-profile)
                settings/       # User settings (/dashboard/settings)
                vcri/           # VCRI projects (/dashboard/vcri)
        components/             # React components (by feature)
            auth/               # Authentication forms
            carbon/             # Carbon profile components
            companies/          # Company CRUD components
            grants/             # Grant cards, search, detail
            matches/            # Match results, scoring
            dashboard/          # Dashboard widgets, stats
            applications/       # Application forms, tracking
            landing/            # Landing page sections
            layout/             # Header, sidebar, footer
            filters/            # Search and filter controls
            ui/                 # shadcn/ui primitives
            CommandPalette.tsx  # Global command palette (Cmd+K)
        lib/                    # Shared utilities
            api/                # API client and hooks
                client.ts       # Type-safe fetch wrapper
                endpoints.ts    # API endpoint definitions
                hooks/          # React Query hooks
                retry.ts        # Retry logic
            utils.ts            # Utility functions
            animations.ts       # Animation variants
        hooks/                  # Custom React hooks
            useToast.ts         # Toast notifications
            useKeyboardShortcuts.ts
            useReducedMotion.ts
            useScrollAnimation.ts
            useAnimatedCounter.ts
        types/                  # TypeScript type definitions
            api.ts              # API types (Request/Response)

Key Pages¶

Route	Page	Auth	Description
`/`	Landing	No	Marketing landing page
`/login`	Login	No	OAuth2 password flow login
`/register`	Register	No	User registration with tenant creation
`/dashboard`	Dashboard Home	Yes	Overview stats and recent activity
`/dashboard/grants`	Grant Search	Yes	Search and filter grants
`/dashboard/companies`	Companies	Yes	Company profile management
`/dashboard/matches`	Matches	Yes	View and manage grant matches
`/dashboard/applications`	Applications	Yes	Track application progress
`/dashboard/carbon-profile`	Carbon Profile	Yes	Scope ½/3 emission input
`/dashboard/settings`	Settings	Yes	User and tenant settings
`/dashboard/vcri`	VCRI Projects	Yes	Carbon credit project management

Development¶

Install Dependencies¶

cd frontend
npm install

Run Development Server¶

npm run dev -- --turbo

The development server starts on http://localhost:3000 with Turbopack for fast refresh.

Environment Variables¶

Variable	Description	Default
`NEXT_PUBLIC_API_URL`	Backend API base URL	`http://localhost:8000`

Build¶

npm run build

Run Tests¶

npm run test            # Vitest
npx playwright test     # E2E tests

Lint¶

npx eslint src/ --ext .ts,.tsx

Layout Structure¶

flowchart TB
    subgraph Root["Root Layout (layout.tsx)"]
        direction TB
        P[Providers<br/>React Query, Theme]
        subgraph Public["Public Routes"]
            LP[Landing Page /]
            LG[Login /login]
            RG[Register /register]
        end
        subgraph Dashboard["Dashboard Layout"]
            direction TB
            SB[Sidebar + Header]
            subgraph Pages["Dashboard Pages"]
                DH[Home]
                GR[Grants]
                CO[Companies]
                MA[Matches]
                AP[Applications]
                CP[Carbon Profile]
                SE[Settings]
            end
        end
    end

The root layout wraps the entire application with providers (React Query, theme). The dashboard layout adds the sidebar navigation and top header bar, which are shared across all authenticated pages.