# ramadan-elgamal/codespark architecture

> Architecture diagram of the GitHub repository ramadan-elgamal/codespark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramadan-elgamal/codespark
- Repository: https://github.com/ramadan-elgamal/codespark

## Overview

##### Project Type and Purpose
- Full-stack web application built with Next.js (App Router) and TypeScript.
- Purpose: Let users input a topic/phase, invoke AI (Google AI via Genkit) to generate and display a programming course, and persist/share the result client-side.

##### File Structure
- src/app/… : Next.js application routes and layouts (login, signup, dashboard, share, pricing, etc.).
- src/ai/… : AI orchestration code (Genkit config + generate-course flow).
- src/components/… : Reusable UI (Radix UI + Tailwind CSS) and dashboard/landing components.
- src/lib/utils.ts & src/hooks/… : Utility functions and custom React hooks (mobile detection, toasts).
- Config: next.config.ts, tailwind.config.ts, apphosting.yaml for static hosting.

##### README for Additional Insights
- No backend database—persistence uses browser localStorage.
- AI calls via Genkit to Google AI; fallbacks use mock generator.
- UI uses React Hook Form + Zod for validation; theme switcher via Context.

##### Main Components & Their Relationships
a. Frontend (Browser)
- Next.js React pages & layouts
- Components (UI primitives, forms, dashboard, share page)
- React Hook Form + Zod for input
- LocalStorage for persistence & activity logs

b. Server-Side Logic (Next.js server actions)
- actions.ts: Exposes server actions to client
- src/ai/flows/generate-course.ts: Orchestrates AI prompt, handles fallback

c. AI Integration
- Genkit (src/ai/genkit.ts): Configures connection to Google AI LLM APIs
- Google AI service (external)

d. Fallback System
- Mock generation logic inside generate-course.ts if external AI fails

e. Static Hosting & Shareable URLs
- App deployed on Netlify (apphosting.yaml)
- “Share” route encodes course data in URL for read-only access

##### Data Flow & Interactions
1. User fills form on client → validated by React Hook Form/Zod.
2. Client calls a Next.js server action (actions.ts) → invoke generate-course flow.
3. generate-course → calls Genkit → Google AI → returns structured course JSON.
4. If AI errors → fallback mock generator.
5. Server action returns course JSON to client.
6. Client stores JSON in localStorage → updates dashboard UI.
7. On “Share,” serializes JSON into URL → shareable page deserializes and renders.

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Presentation layer in src/app & src/components/ui
- Business logic in src/ai & server actions
- Persistence in localStorage (client-side data store)
- Componentization: Reusable UI primitives (Radix + Tailwind)
- Schema-driven design: Zod for input/output validation
- Resilience: Fallback logic for AI unavailability
- Static hosting: No dedicated backend server or database

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Browser (Client)"
        direction TB
        NextRouter["Next.js App Router"]:::frontend
        Login["Login Page"]:::frontend
        Signup["Signup Page"]:::frontend
        DashboardLayout["Dashboard Layout"]:::frontend
        DashboardHome["Dashboard Home"]:::frontend
        AccountSettings["Account Settings"]:::frontend
        CoursesList["Courses List"]:::frontend
        CourseDetail["Course Detail"]:::frontend
        CourseGenerationUI["Course Generation UI"]:::frontend
        ShareCourse["Shareable Course Page"]:::frontend
        Pricing["Pricing Page"]:::frontend
        GlobalLayout["Global Layout"]:::frontend
        GlobalCSS["Global Styles (globals.css)"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
        AuthForm["AuthForm Component"]:::frontend
        LandingHeader["Landing Header"]:::frontend
        LandingFooter["Landing Footer"]:::frontend
        CourseGeneratorComp["CourseGenerator Component"]:::frontend
        ThemeProvider["ThemeProvider"]:::frontend
        ThemeToggle["ThemeToggle"]:::frontend
        UseMobile["use-mobile Hook"]:::frontend
        UseToast["use-toast Hook"]:::frontend
        Utils["Utility Functions"]:::frontend
    end

    %% Server Actions Layer
    subgraph "Next.js Server Actions"
        direction TB
        Actions["actions.ts Server Actions"]:::server
    end

    %% AI Layer
    subgraph "AI Integration"
        direction TB
        GenerateFlow["Generate-Course Flow"]:::ai
        GenkitMod["Genkit Configuration"]:::ai
        DevStub["Dev AI Stub"]:::ai
    end

    %% External Service
    subgraph "External AI Service"
        direction TB
        GoogleAI["Google AI"]:::external
    end

    %% Storage Layer
    LocalStorage["Browser LocalStorage"]:::storage

    %% Hosting Layer
    subgraph "Static Hosting"
        direction TB
        Netlify["Netlify (apphosting.yaml)"]:::hosting
        NextConfig["next.config.ts"]:::hosting
        TailwindConfig["tailwind.config.ts"]:::hosting
        TSConfig["tsconfig.json"]:::hosting
    end

    %% Data Flows
    CourseGenerationUI -->|"submit form"| Actions
    Actions -->|"invoke generateCourse"| GenerateFlow
    GenerateFlow -->|"call Genkit"| GenkitMod
    GenkitMod -->|"request course JSON"| GoogleAI
    GoogleAI -->|"response JSON"| GenkitMod
    GenerateFlow -->|"return data"| Actions
    GenerateFlow -.->|"fallback on error"| DevStub
    Actions -->|"send course JSON"| CourseGenerationUI
    CourseGenerationUI -->|"store data"| LocalStorage
    CourseGenerationUI -->|"read data"| LocalStorage
    ShareCourse -->|"serialize/deserialize URL"| LocalStorage

    %% Click Events
    click NextRouter "https://github.com/ramadan-elgamal/codespark/tree/master/src/app"
    click Login "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/login/page.tsx"
    click Signup "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/signup/page.tsx"
    click DashboardLayout "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/layout.tsx"
    click DashboardHome "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/page.tsx"
    click AccountSettings "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/account/page.tsx"
    click CoursesList "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/courses/page.tsx"
    click CourseDetail "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/courses/[courseId]/page.tsx"
    click CourseGenerationUI "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/dashboard/generate/page.tsx"
    click ShareCourse "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/share/[courseData]/page.tsx"
    click Pricing "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/pricing/page.tsx"
    click GlobalLayout "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/layout.tsx"
    click GlobalCSS "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/globals.css"
    click Actions "https://github.com/ramadan-elgamal/codespark/blob/master/src/app/actions.ts"
    click GenkitMod "https://github.com/ramadan-elgamal/codespark/blob/master/src/ai/genkit.ts"
    click GenerateFlow "https://github.com/ramadan-elgamal/codespark/blob/master/src/ai/flows/generate-course.ts"
    click DevStub "https://github.com/ramadan-elgamal/codespark/blob/master/src/ai/dev.ts"
    click UIPrimitives "https://github.com/ramadan-elgamal/codespark/tree/master/src/components/ui"
    click CourseGeneratorComp "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/dashboard/CourseGenerator.tsx"
    click LandingHeader "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/landing/Header.tsx"
    click LandingFooter "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/landing/Footer.tsx"
    click AuthForm "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/auth/AuthForm.tsx"
    click ThemeProvider "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/ThemeProvider.tsx"
    click ThemeToggle "https://github.com/ramadan-elgamal/codespark/blob/master/src/components/ThemeToggle.tsx"
    click UseMobile "https://github.com/ramadan-elgamal/codespark/blob/master/src/hooks/use-mobile.tsx"
    click UseToast "https://github.com/ramadan-elgamal/codespark/blob/master/src/hooks/use-toast.ts"
    click Utils "https://github.com/ramadan-elgamal/codespark/blob/master/src/lib/utils.ts"
    click Netlify "https://github.com/ramadan-elgamal/codespark/blob/master/apphosting.yaml"
    click NextConfig "https://github.com/ramadan-elgamal/codespark/blob/master/next.config.ts"
    click TailwindConfig "https://github.com/ramadan-elgamal/codespark/blob/master/tailwind.config.ts"
    click TSConfig "https://github.com/ramadan-elgamal/codespark/blob/master/tsconfig.json"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064
    classDef server fill:#E8F5E9,stroke:#1B5E20
    classDef ai fill:#FFF3E0,stroke:#E65100
    classDef external fill:#FFEBEE,stroke:#B71C1C
    classDef storage fill:#FFF9C4,stroke:#F57F17
    classDef hosting fill:#ECEFF1,stroke:#546E7A

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Client (light blue)"]:::frontend
        L2["Server Actions (green)"]:::server
        L3["AI Flow (orange)"]:::ai
        L4["External AI (red)"]:::external
        L5["LocalStorage (yellow)"]:::storage
        L6["Hosting & Config (gray)"]:::hosting
    end
```
