Skip to main content

​
Application Architecture

Open Tarteel is built as a Progressive Web App (PWA) using Next.js 15 with React 19, designed to provide offline-first Quran streaming capabilities.

​
Technology Stack

Frontend Framework

  • Next.js 15.4.2 with App Router
  • React 19.1.0 with Server Components
  • TypeScript 5 for type safety

State Management

  • Jotai 2.11.1 for atomic state
  • localStorage persistence
  • Jotai DevTools for debugging

Styling

  • Tailwind CSS 3.4.1
  • Tailwind Animated
  • Custom CSS variables

PWA Features

  • Serwist 9.0.12 service worker
  • Offline audio caching
  • Install prompts

​
Architecture Diagram

​
Project Structure

src/
├── app/                    # Next.js App Router
│   ├── layout.tsx         # Root layout with providers
│   ├── page.tsx           # Home page with reciter selector
│   ├── manifest.ts        # PWA manifest configuration
│   ├── reciter/[id]/     # Dynamic reciter pages
│   ├── about/            # Static pages
│   └── api/              # API routes
├── components/            # React components
│   ├── player.tsx        # Audio player component
│   ├── player-controls.tsx
│   ├── reciter-selector.tsx
│   └── audio-bars-visualizer.tsx
├── jotai/                # State management
│   ├── atom.ts           # Global atoms
│   └── create-atom-with-storage.ts
├── utils/                # Utility functions
│   ├── api.ts            # API integration
│   └── storage/          # Storage helpers
├── types/                # TypeScript types
└── sw.ts                 # Service worker

​
Core Features

Next.js App Router provides:
  • Initial page load optimization
  • SEO-friendly reciter pages
  • Automatic code splitting
  • Image optimization
src/app/reciter/[id]/page.tsx
export default async function ReciterPage({ params }) {
  // Server-side data fetching
  const reciter = await getReciter(params.id);
  return <ReciterPageClient reciter={reciter} />;
}
React components hydrate on the client with:
  • Jotai state restoration from localStorage
  • Audio player initialization
  • Service worker registration
src/app/layout.tsx
'use client';
export default function RootLayout({ children }) {
  const [isFullscreen, setIsFullscreen] = useAtom(fullscreenAtom);
  // Sync fullscreen state with browser
  useEffect(() => {
    document.addEventListener('fullscreenchange', onFullscreenChange);
  }, []);
}
The app works without JavaScript but enhances with:
  • Audio playback controls
  • Offline caching
  • Real-time visualizers
  • Keyboard shortcuts

​
Configuration Files

next.config.ts
import withSerwistInit from '@serwist/next';
import withBundleAnalyzer from '@next/bundle-analyzer';

const withSerwist = withSerwistInit({
  swSrc: 'src/sw.ts',
  swDest: 'public/sw.js',
  cacheOnNavigation: true,
  disable: !isProduction,
  maximumFileSizeToCacheInBytes: 100 * 1024 * 1024, // 100MB
});

const nextConfig: NextConfig = {
  reactStrictMode: !isProduction,
  transpilePackages: ['jotai-devtools'],
  compiler: {
    removeConsole: isProduction && { exclude: ['error'] },
  },
};

​
Performance Optimizations

Bundle Size

  • Code splitting per route
  • Dynamic imports for heavy components
  • Tree shaking unused code
  • Bundle analyzer integration

Caching Strategy

  • Static assets cached indefinitely
  • API responses cached 1 hour
  • Audio files cached 7 days
  • Service worker precaching

Network Optimization

  • Lazy loading images
  • Preconnect to MP3Quran servers
  • HTTP/2 server push
  • Compression (Brotli/gzip)

Runtime Performance

  • React 19 concurrent features
  • Jotai atomic updates
  • Web Workers for audio processing
  • RequestIdleCallback for non-critical tasks
Production Mode: In production, the app removes console logs (except errors), enables strict mode optimizations, and activates the service worker for offline support.

​
Development Workflow

# Install dependencies
npm install

# Development server with Turbopack
npm run dev:turbo

# Type checking
npm run type-check

# Production build
npm run build

# Analyze bundle size
ANALYZE=true npm run build

​
Browser Support

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+
  • Mobile browsers (iOS Safari, Chrome Android)
The architecture is designed for scalability, offline-first capabilities, and optimal performance across all devices.

Build docs developers (and LLMs) love

Get started for freeTalk to us