# evantechdev/one-calendar architecture

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

- Interactive diagram: https://gitdiagram.com/evantechdev/one-calendar
- Repository: https://github.com/evantechdev/one-calendar

## Overview

##### Project type and purpose
- This is a full-stack, single-page web application built with Next.js 14 (App Router).
- It provides a weekly calendar UI, user authentication, AI-powered features, optional cloud sync, weather integration, and local data storage.

##### File structure
- Top-level “app” directory holds all Next.js routes, layouts, and API endpoints:
- app/page.tsx, app/layout.tsx, app/not-found.tsx, app/sitemap.ts
- app/(app) and app/(auth) folders for protected vs. public pages
- app/api/{blob, chat, share, weather}/route.ts for serverless functions
- “components” folder groups UI building blocks by domain (account, analytics, event, home, sidebar, ui, view).
- “hooks” and “lib” folders contain custom React hooks and utility libraries (i18n, icsUtils, notifications, time-analytics).
- Configuration files: next.config.mjs, tailwind.config.ts, tsconfig.json, middleware.ts, .env.example

##### README for additional insights
- Frontend: Next.js + React + TypeScript + Tailwind + shadcn/ui
- Auth: Clerk (third-party session management)
- Data storage:
- Client-side: LocalStorage
- Cloud sync: Vercel Blob or Misskey Drive
- External APIs:
- Groq API (AI scheduling suggestions)
- OpenWeather API
- Hosting: Vercel or Netlify; runtime target Bun or Node

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        UI["React UI Components"]:::client
        Context["Context Providers"]:::client
        Hooks["Custom Hooks"]:::client
        Lib["Utility Libraries"]:::util
        LocalStorage["LocalStorage"]:::storage
    end

    %% Frontend Server Layer
    subgraph "Next.js Frontend Server" 
        direction TB
        PagesRoot["App Router: Root Layout & Pages"]:::server
        AuthPages["Public Auth Pages"]:::server
        AppPages["Protected App Pages"]:::server
        Middleware["Auth Middleware"]:::server
        API["Next.js API Routes"]:::api
    end

    %% API Routes Layer
    subgraph "Serverless API Routes" 
        direction TB
        BlobAPI["Blob Storage API"]:::api
        ChatAPI["AI Chat API"]:::api
        ShareAPI["Share Management API"]:::api
        WeatherAPI["Weather API"]:::api
    end

    %% External Services Layer
    subgraph "External Services" 
        direction TB
        Clerk["Clerk Auth Service"]:::external
        BlobService["Vercel Blob / Misskey Drive"]:::external
        Groq["Groq AI Service"]:::external
        WeatherExt["OpenWeather API"]:::external
    end

    %% Data Flow
    UI -->|"renders via SSR/CSR"| PagesRoot
    UI -->|"navigates"| AuthPages
    UI -->|"navigates"| AppPages
    UI -->|"uses"| Context
    UI -->|"calls"| Hooks
    UI -->|"imports"| Lib
    UI -->|"reads/writes"| LocalStorage

    PagesRoot -->|"(middleware)"| Middleware
    AuthPages -->|"(middleware)"| Middleware
    AppPages -->|"(middleware)"| Middleware

    UI -->|"/api/* calls"| API
    API -->|validate session| Clerk
    API -->|cloud sync| BlobService
    BlobAPI -->|list/vercel| BlobService
    ChatAPI -->|schedule| Groq
    WeatherAPI -->|fetch| WeatherExt
    ShareAPI -->|vercel| BlobService

    LocalStorage -->|backup| BlobAPI

    %% Click Events
    click PagesRoot "https://github.com/evantechdev/one-calendar/blob/main/app/layout.tsx"
    click PagesRoot "https://github.com/evantechdev/one-calendar/blob/main/app/page.tsx"
    click PagesRoot "https://github.com/evantechdev/one-calendar/blob/main/app/not-found.tsx"
    click PagesRoot "https://github.com/evantechdev/one-calendar/blob/main/app/sitemap.ts"
    click AuthPages "https://github.com/evantechdev/one-calendar/tree/main/app/(auth)"
    click AppPages "https://github.com/evantechdev/one-calendar/tree/main/app/(app)"
    click BlobAPI "https://github.com/evantechdev/one-calendar/tree/main/app/api/blob"
    click ChatAPI "https://github.com/evantechdev/one-calendar/blob/main/app/api/chat/route.ts"
    click ChatAPI "https://github.com/evantechdev/one-calendar/blob/main/app/api/chat/schedule/route.ts"
    click ShareAPI "https://github.com/evantechdev/one-calendar/blob/main/app/api/share/route.ts"
    click ShareAPI "https://github.com/evantechdev/one-calendar/blob/main/app/api/share/vercel/route.ts"
    click WeatherAPI "https://github.com/evantechdev/one-calendar/blob/main/app/api/weather/route.ts"
    click UI "https://github.com/evantechdev/one-calendar/tree/main/components/ui"
    click Context "https://github.com/evantechdev/one-calendar/blob/main/components/context/CalendarContext.tsx"
    click Hooks "https://github.com/evantechdev/one-calendar/blob/main/hooks/useLocalStorage.ts"
    click Lib "https://github.com/evantechdev/one-calendar/blob/main/lib/i18n.ts"
    click Middleware "https://github.com/evantechdev/one-calendar/blob/main/middleware.ts"
    click UI "https://github.com/evantechdev/one-calendar/blob/main/tailwind.config.ts"

    %% Styling
    classDef client fill:#D6EAF8,stroke:#2980B9,color:#154360
    classDef server fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef api fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef external fill:#FDEDEC,stroke:#E74C3C,color:#78281F
    classDef storage fill:#F9E79F,stroke:#D4AC0D,color:#7E5109
    classDef util fill:#E8DAEF,stroke:#8E44AD,color:#4A235A
```
