Frontend Documentation
Comprehensive guide to the Odysee.ai frontend monorepo
Overview
Odysee.ai is a modern airline operations platform built with Next.js 15, React 19, and TypeScript. The frontend is structured as a Turborepo monorepo, enabling efficient code sharing and build optimization across multiple applications and packages.
What You'll Find Here
This documentation covers everything from initial setup to advanced architecture patterns. Whether you're setting up your development environment, implementing new features, or understanding the deployment pipeline, you'll find detailed, practical guidance.
Quick Start
Getting Started
Set up your development environment and run the app locally
Contributing
Learn the Git Flow workflow and coding standards
Architecture
Understand the monorepo structure and design patterns
Deployment
CI/CD pipeline with GitHub Actions and Vercel
Technology Stack
The application uses a modern, production-ready stack optimized for developer experience and performance:
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 15.1 | React framework with App Router |
| React | 19 | UI library with Server Components |
| TypeScript | 5.7 | Type safety and developer experience |
| Node.js | ≥20.12.2 | Runtime environment |
| pnpm | 9.1.0 | Fast, efficient package manager |
| Technology | Version | Purpose | | --- | --- | --- | | Material-UI | 7.2 | Component library and design system | | Emotion | Latest | CSS-in-JS styling solution | | Phosphor Icons | 2.1.7 | Icon library | | @shared/ui | workspace | Custom component library |
| Technology | Version | Purpose | | --- | --- | --- | | TanStack Query | 5.85.3 | Server state management | | Zod | 3.24.1 | Schema validation | | React Hook Form | Latest | Form state management | | Clerk | 6.9.9 | Authentication |
| Technology | Version | Purpose |
|---|---|---|
| Turborepo | 2.4.4 | Monorepo build system |
| ESLint | Latest | Code linting |
| Biome | Latest | Fast formatter and linter |
| Husky | Latest | Git hooks |
Architecture
The monorepo contains three applications and four shared packages:
Applications
Shared Packages
Key Features
Guest Disruptions
Comprehensive system for managing flight schedule changes and passenger impacts. Identifies disrupted itineraries, analyzes passenger segments, displays schedule timelines, and finds alternative flight pathways.
Learn more: Guest Disruptions Documentation
Notifications
Real-time notification system powered by Novu. Delivers in-app notifications with automatic Clerk authentication sync and Material-UI theme integration.
Learn more: Notifications Documentation
Authentication
Multi-provider authentication supporting Clerk, Auth0, and AWS Cognito. Seamless integration with Next.js middleware and Server Components.
Learn more: Authentication Documentation
Development Workflow
The project follows Git Flow with automated deployments:
Feature Development
Create a feature branch, develop locally, and open a PR to develop. Each PR gets an automatic preview deployment.
Integration Testing
Merged features deploy to the develop environment (dev.odysee.ai) for integration testing.
Release Preparation
Create a release branch from develop. Automatically deploys to staging (staging.odysee.ai) for QA.
Production Release
Merge to main triggers production deployment, creates a GitHub release, and merges back to develop.
Learn more: Deployment Guide
Data Fetching Pattern
The application uses a consistent pattern combining Server Actions with React Query:
- Server Actions handle API communication and authentication
- React Query hooks manage client-side caching and state
- Centralized query keys ensure consistent cache invalidation
// Custom hook wrapping Server Action
export function useGuestDisruptions(scheduleId: string, params?: Params) {
return useQuery({
queryKey: queryKeys.guestDisruptions.list(scheduleId, params),
queryFn: () => getGuestDisruptions(scheduleId, params),
staleTime: 5 * 60 * 1000,
})
}Learn more: Data Fetching Documentation
Code Quality
The project enforces high code quality standards through automated tooling:
Performance
The monorepo is optimized for both build-time and runtime performance:
Build Optimization:
- Turborepo caches build outputs, skipping unchanged packages
- Remote caching shares results across team members
- Parallel task execution maximizes CPU usage
Runtime Optimization:
- Server Components reduce client-side JavaScript
- React Query caches API responses
- Code splitting and lazy loading minimize bundle sizes
- Next.js Image component optimizes images automatically
Getting Help
Contributing Guide
Git workflow, commit standards, and PR process
Architecture Docs
Deep dive into monorepo structure and patterns
Component Library
Browse and use shared UI components
Troubleshooting
Common issues and solutions
Ready to start? Head to Getting Started to set up your development environment.