# moonixt/kot-space architecture

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

- Interactive diagram: https://gitdiagram.com/moonixt/kot-space
- Repository: https://github.com/moonixt/kot-space

## Overview

##### Project Type and Purpose
- This is a full-stack Progressive Web App (PWA) built with Next.js and TypeScript.
- It’s a responsive, note-taking application (“Кot-space”) featuring markdown support, tag organization, encrypted storage, user authentication via Supabase, and Stripe integration for payments.

##### File Structure Analysis
- **app/**: Next.js 13+ App Router directory holding all page routes, API endpoints, layouts, and global styles.
- **app/api/**: Serverless functions (chat, Stripe customer portal, Stripe webhook).
- **app/[feature]/**: Pages for chat, dashboard, notes, editor, authentication (login, signup, reset/update password), settings, pricing, etc.
- **components/** under app: UI elements specific to pages (AuthenticatedRoute, CalendarView, ChatAssistant, etc.).
- **globals.css**, **layout.tsx**: Global styling and root layout.
- **components/**: Global UI component library (button, checkbox, dialog, etc.) and i18n providers.
- **context/**: React Context providers (AuthContext, ThemeContext, MusicPlayerContext).
- **lib/**: Utility modules (Supabase client, event emitter, subscription checker, encryption helper).
- **i18n/**: Internationalization setup and locale files.
- **forge.config.js**, **next.config.ts**, build configs, ESLint, Tailwind, TypeScript config.

##### Main System Components
a. Client (Browser/PWA)
- Next.js React components (app pages + UI library)
- Service Worker (public/sw.js) for offline support
- Context Providers (Auth, Theme, MusicPlayer)
- i18n TranslationProvider
- Responsive/adaptive layout (TailwindCSS + custom CSS in globals.css)
b. Next.js Server (Serverless Functions)
- API Routes under app/api:
- /chat → AI-driven chat assistant
- /stripe/customer-portal → Stripe customer portal integration
- /webhook/stripe → Stripe event webhook handler
- Supabase client usage for authentication and database queries
c. Backend Services
- Supabase:
- Auth (sign up, login, password reset)
- Database (notes, tags, metadata)
- Storage (if attachments)
- Stripe (payment processing, subscription management)
- External AI service (if used by chat route)
d. Utilities & Helpers
- lib/utils.ts, lib/encryption.ts: data encryption/decryption before storing notes
- lib/eventEmitter: in-app event handling (e.g., for real-time UI updates)

##### Component Relationships & Data Flow
- User interacts with the Next.js PWA client →
- Client routes requests to Next.js serverless API endpoints (via fetch/axios) →
- API routes use Supabase SDK to authenticate, read/write note data →
- Stripe API is called from serverless functions for payment operations →
- Stripe sends webhook events → Next.js /api/webhook/stripe updates subscription status in Supabase →
- Client listens for changes (via polling or real-time subscriptions) and updates UI.

##### Architectural Patterns & Design Principles
- **Serverless Functions**: All backend logic lives in Next.js API routes.
- **Context-Driven State Management**: Auth, theme, and music contexts wrap the app for global state.
- **i18n**: Dynamic locale loading with React context and TranslationProvider.
- **PWA**: Service worker for offline caching and installability.
- **Encryption at Rest**: Note content encrypted on the client via Encryption component before sending to Supabase.
- **Responsive/Adaptive Layout**: TailwindCSS + CSS media queries and utility classes used throughout components.

##### Final Delivery
- Capturing all serverless routes, contexts, i18n, PWA service worker, and external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        NextClient["Next.js PWA Client"]:::client
        ServiceWorker["Service Worker"]:::client
        subgraph "Responsive UI Layer"
            direction TB
            LayoutEngine["Responsive Layout Engine<br/>(TailwindCSS)"]:::client
            AdaptiveComponents["Adaptive Components<br/>(sidebox, tables, editor, clock, blackbox, music)"]:::client
        end
        AuthCtx["AuthContext Provider"]:::client
        ThemeCtx["ThemeContext Provider"]:::client
        MusicCtx["MusicPlayerContext Provider"]:::client
        I18nProv["TranslationProvider"]:::client
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        direction TB
        APIChat["API: /chat"]:::api
        APIPortal["API: /stripe/customer-portal"]:::api
        APIWebhook["API: /webhook/stripe"]:::api
        SupabaseSDK["Supabase Client SDK"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SupabaseAuth["Supabase Auth"]:::external
        StripeSvc["Stripe"]:::external
        AIService["External AI Service"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        SupabaseDB["Supabase Database & Storage"]:::datastore
    end

    %% Connections
    User["User"] -->|Interacts with| NextClient
    NextClient -->|"calls API"| APIChat
    NextClient -->|"calls API"| APIPortal
    NextClient -->|"calls API"| APIWebhook
    NextClient -->|"uses SW"| ServiceWorker
    NextClient -->|"uses contexts"| AuthCtx
    NextClient -->|"uses contexts"| ThemeCtx
    NextClient -->|"uses contexts"| MusicCtx
    NextClient -->|"uses i18n"| I18nProv
    APIChat -->|"uses SDK"| SupabaseSDK
    APIPortal -->|"uses SDK"| SupabaseSDK
    APIWebhook -->|"uses SDK"| SupabaseSDK
    SupabaseSDK -->|"auth & queries"| SupabaseAuth
    SupabaseAuth -->|"stores data"| SupabaseDB
    SupabaseSDK -->|"reads/writes"| SupabaseDB
    APIPortal -->|"payment ops"| StripeSvc
    StripeSvc -->|Webhook events| APIWebhook
    APIChat -->|optional calls| AIService

    %% Click Events
    click NextClient "https://github.com/moonixt/kot-space/tree/main/app/"
    click ServiceWorker "https://github.com/moonixt/kot-space/blob/main/public/sw.js"
    click LayoutEngine "https://github.com/moonixt/kot-space/blob/main/app/globals.css"
    click AuthCtx "https://github.com/moonixt/kot-space/blob/main/context/AuthContext.tsx"
    click ThemeCtx "https://github.com/moonixt/kot-space/blob/main/context/ThemeContext.tsx"
    click MusicCtx "https://github.com/moonixt/kot-space/blob/main/context/MusicPlayerContext.tsx"
    click I18nProv "https://github.com/moonixt/kot-space/blob/main/components/TranslationProvider.tsx"
    click APIChat "https://github.com/moonixt/kot-space/blob/main/app/api/chat/route.ts"
    click APIPortal "https://github.com/moonixt/kot-space/blob/main/app/api/stripe/customer-portal/route.ts"
    click APIWebhook "https://github.com/moonixt/kot-space/blob/main/app/api/webhook/stripe/route.ts"
    click SupabaseSDK "https://github.com/moonixt/kot-space/blob/main/lib/supabase.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000
    classDef api fill:#d4edda,stroke:#28a745,color:#000
    classDef external fill:#ffe5b4,stroke:#ff9900,color:#000
    classDef datastore fill:#e2d4f0,stroke:#800080,color:#000
```
