# adilzhany/ay-directory architecture

> Architecture diagram of the GitHub repository adilzhany/ay-directory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adilzhany/ay-directory
- Repository: https://github.com/adilzhany/ay-directory

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered Next.js 13 application (“app” folder) that serves as a directory of startups (AY Directory).
- It uses Sanity.io as a headless CMS for content storage and NextAuth for GitHub-based user authentication.

##### File structure
- Top-level “app” directory implements Next.js App Router:
- app/layout.tsx & globals.css — global shell, CSS/ Tailwind setup
- app/page.tsx — homepage
- app/(root)/startup & app/(root)/user — dynamic routes for startups & user profiles
- app/api/auth/[...nextauth]/route.ts — NextAuth API route
- app/api/* — potential other API endpoints
- “components” folder holds UI React components (server & client). “components/ui” contains atomic UI elements.
- “lib” contains shared utilities (actions.ts, utils.ts, validation.ts) called both server- and client-side.
- “hooks” houses custom React hooks (e.g. use-toast).
- “sanity” directory encapsulates CMS integration:
- sanity/lib/client.ts — configured Sanity client for reading
- sanity/lib/write-client.ts — client with write privileges
- sanity/lib/queries.ts — GROQ queries
- sanity/schemaTypes — content schema definitions (author, playlist, startup)
- sanity/structure.ts — Studio customization
- Config files: next.config.ts, postcss.config.mjs, tailwind.config.ts, tsconfig.json.
- README highlights the use of Next.js, Sanity CMS, NextAuth, Tailwind, and environment variable setup.

##### Main components
a. Frontend (Client)
- Browser / user agent that loads SSR/SSG pages and hydrates client components.
- Components: Navbar, SearchForm, StartupCard, etc.
b. Next.js Server (App Router)
- Route handlers in “app” folder: server components fetch data from Sanity via client.
- API routes: NextAuth for authentication, potential custom REST/GraphQL.
c. Sanity Headless CMS
- Hosted service storing content (startups, authors, playlists).
- Two clients: read-only and write (for privileged operations).
d. Authentication Provider
- NextAuth server route integrates with GitHub OAuth endpoints.
- External service: GitHub OAuth API.
e. Database / CDN (optional)
- Sanity’s internal datastore + CDN-delivered assets.
f. Edge/CDN (if deployed on Vercel or similar)
- Caching layer for SSR/SSG pages, static assets.

##### Relationships and data flows
- Browser → Next.js SSR/SSG: HTTP requests for pages (e.g. GET /startup/123)
- Next.js Server → Sanity (read-client): fetch content using GROQ queries
- Next.js Server → Sanity (write-client): for privileged write operations (if any)
- Browser → Next.js API Route (/api/auth/[...nextauth]): sign-in, callback flows
- NextAuth → GitHub OAuth Endpoint: token exchange, user profile fetch
- Next.js Server → Database/CDN: static file delivery (fonts, images in /public)

##### Architectural patterns and design principles
- App Router pattern (Next.js 13): separation of server components (data fetching) and client components (interactive UI).
- Headless CMS: Sanity as an external service decouples content from presentation.
- Modular UI: atomic design in “components/ui”, domain components in “components”.
- Utility libraries in “lib” abstract business logic and validation.
- API route segregation: authentication routes under /api/auth, future REST endpoints can live under /api/*.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend (Client)" 
        style Frontend fill:#E8F0FE,stroke:#5B8DEF,stroke-width:2px
        Browser["Browser (User Agent)"]:::ui
        Navbar["Navbar"]:::ui
        SearchForm["SearchForm"]:::ui
        SearchFormReset["SearchFormReset"]:::ui
        StartupCard["StartupCard"]:::ui
        StartupForm["StartupForm"]:::ui
        UserStartups["UserStartups"]:::ui
        ViewWrapper["View (Generic View Wrapper)"]:::ui
        UI_Elements["Atomic UI Elements"]:::ui
    end

    %% Next.js Server Layer
    subgraph "Next.js Server (App Router & API)" 
        style NextJS fill:#E6F9E6,stroke:#34A853,stroke-width:2px
        AppLayout["Global Layout & Styles"]:::server
        RootLayout["Root Layout & Homepage"]:::server
        StartupRoutes["Startup Routes"]:::server
        UserRoute["User Profile Route"]:::server
        NextAuthAPI["NextAuth API Route"]:::server
        API_Other["Other API Endpoints"]:::server
    end

    %% Sanity CMS
    subgraph "Sanity Headless CMS" 
        style Sanity fill:#FFF4E5,stroke:#FB8C00,stroke-width:2px
        ReadClient["Sanity Read Client"]:::external
        LiveClient["Sanity Live Client"]:::external
        WriteClient["Sanity Write Client"]:::external
        Queries["GROQ Queries"]:::external
        Schemas["Schema Definitions"]:::external
    end

    %% Studio Configuration
    subgraph "Sanity Studio" 
        style Studio fill:#FFF4E5,stroke:#FB8C00,stroke-width:2px
        StudioEntry["Studio Entry Point"]:::external
        Structure["Custom Structure"]:::external
        ConfigCLI["Sanity Config & CLI"]:::external
    end

    %% External Auth Provider
    subgraph "Authentication Provider" 
        style AuthProv fill:#FFF4E5,stroke:#FB8C00,stroke-width:2px
        GitHubOAuth["GitHub OAuth"]:::external
    end

    %% Edge/CDN Layer
    subgraph "Edge / CDN" 
        style CDN fill:#F5F5F5,stroke:#AAAAAA,stroke-width:2px
        CDNLayer["CDN / Cache"]:::cdn
    end

    %% Shared Utilities & Hooks
    subgraph "Shared & Hooks" 
        style Shared fill:#E6F9E6,stroke:#34A853,stroke-width:2px
        Actions["Actions & Data Helpers"]:::server
        Utils["General Utilities"]:::server
        Validation["Validation Schemas"]:::server
        ToastHook["use-toast Hook"]:::server
    end

    %% Configuration Files
    subgraph "Config & Build Files"
        style Config fill:#F5F5F5,stroke:#AAAAAA,stroke-width:2px
        NextConfig["next.config.ts / tsconfig.json"]:::config
        TailwindConfig["tailwind.config.ts / postcss.config.mjs"]:::config
        ESLintConfig["eslint.config.mjs"]:::config
        Manifest["package.json / package-lock.json"]:::config
    end

    %% Connections
    Browser -->|"HTTP Page Requests"| AppLayout
    Browser -->|"API Requests"| NextAuthAPI
    AppLayout --> RootLayout
    RootLayout --> StartupRoutes
    RootLayout --> UserRoute
    StartupRoutes --> ReadClient
    StartupRoutes --> WriteClient
    ReadClient --> Queries
    WriteClient --> Queries
    NextAuthAPI -->|Token Exchange| GitHubOAuth
    AppLayout -->|Serves Static Assets| CDNLayer
    CDNLayer -.->|Cached Responses| Browser
    Actions --> AppLayout
    Utils --> AppLayout
    Validation --> AppLayout
    ToastHook --> StartupRoutes

    %% Click Events - Frontend
    click Navbar "https://github.com/adilzhany/ay-directory/blob/main/components/Navbar.tsx"
    click SearchForm "https://github.com/adilzhany/ay-directory/blob/main/components/SearchForm.tsx"
    click SearchFormReset "https://github.com/adilzhany/ay-directory/blob/main/components/SearchFormReset.tsx"
    click StartupCard "https://github.com/adilzhany/ay-directory/blob/main/components/StartupCard.tsx"
    click StartupForm "https://github.com/adilzhany/ay-directory/blob/main/components/StartupForm.tsx"
    click UserStartups "https://github.com/adilzhany/ay-directory/blob/main/components/UserStartups.tsx"
    click ViewWrapper "https://github.com/adilzhany/ay-directory/blob/main/components/View.tsx"
    click UI_Elements "https://github.com/adilzhany/ay-directory/tree/main/components/ui/"

    %% Click Events - Next.js App Router
    click AppLayout "https://github.com/adilzhany/ay-directory/blob/main/app/layout.tsx"
    click RootLayout "https://github.com/adilzhany/ay-directory/blob/main/app/(root)/layout.tsx"
    click StartupRoutes "https://github.com/adilzhany/ay-directory/blob/main/app/(root)/startup/[id]/page.tsx"
    click NextAuthAPI "https://github.com/adilzhany/ay-directory/blob/main/app/api/auth/[...nextauth]/route.ts"
    click UserRoute "https://github.com/adilzhany/ay-directory/blob/main/app/(root)/user/[id]/page.tsx"

    %% Click Events - Sanity CMS
    click ReadClient "https://github.com/adilzhany/ay-directory/blob/main/sanity/lib/client.ts"
    click LiveClient "https://github.com/adilzhany/ay-directory/blob/main/sanity/lib/live.ts"
    click WriteClient "https://github.com/adilzhany/ay-directory/blob/main/sanity/lib/write-client.ts"
    click Queries "https://github.com/adilzhany/ay-directory/blob/main/sanity/lib/queries.ts"
    click Schemas "https://github.com/adilzhany/ay-directory/tree/main/sanity/schemaTypes/"

    %% Click Events - Sanity Studio
    click StudioEntry "https://github.com/adilzhany/ay-directory/blob/main/app/studio/[[...tool]]/page.tsx"
    click Structure "https://github.com/adilzhany/ay-directory/blob/main/sanity/structure.ts"
    click ConfigCLI "https://github.com/adilzhany/ay-directory/blob/main/sanity.config.ts"

    %% Click Events - Shared & Hooks
    click Actions "https://github.com/adilzhany/ay-directory/blob/main/lib/actions.ts"
    click Utils "https://github.com/adilzhany/ay-directory/blob/main/lib/utils.ts"
    click Validation "https://github.com/adilzhany/ay-directory/blob/main/lib/validation.ts"
    click ToastHook "https://github.com/adilzhany/ay-directory/blob/main/hooks/use-toast.ts"

    %% Click Events - Config Files
    click NextConfig "https://github.com/adilzhany/ay-directory/blob/main/next.config.ts"
    click TailwindConfig "https://github.com/adilzhany/ay-directory/blob/main/tailwind.config.ts"
    click ESLintConfig "https://github.com/adilzhany/ay-directory/blob/main/eslint.config.mjs"
    click Manifest "https://github.com/adilzhany/ay-directory/blob/main/package.json"

    %% Classes
    classDef ui fill:#E8F0FE,stroke:#5B8DEF,color:#0B3D91
    classDef server fill:#E6F9E6,stroke:#34A853,color:#0F5132
    classDef external fill:#FFF4E5,stroke:#FB8C00,color:#7C4D02
    classDef cdn fill:#F5F5F5,stroke:#AAAAAA,color:#555555
    classDef config fill:#F5F5F5,stroke:#AAAAAA,color:#555555
```
