# sleepy-gogo/coonspace architecture

> Architecture diagram of the GitHub repository sleepy-gogo/coonspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sleepy-gogo/coonspace
- Repository: https://github.com/sleepy-gogo/coonspace

## Overview

##### Project Type and Purpose
- CoonSpace is a full-stack web application built with Next.js 14 and TypeScript. Its primary purpose is to allow users to share markdown notes instantly, with features for drag & drop uploads, custom URLs, syntax highlighting, and an integrated admin panel.
- The README highlights its tech stack (Next.js, Tailwind, Clerk, Turso, UploadThing, PostHog, Upstash) and key functionalities (notes sharing, authentication, admin management). This makes it clear that the application combines both client-side and server-side components with multiple external services.

##### Key File Structure Insights
- The top-level files (e.g., .env.example, next.config.js, package.json) indicate configuration and dependency management.
- The src/app directory (with subdirectories like (Content), (Content)/(Landing), (Content)/(Main) etc.) defines the Next.js app’s routing with clear separation between landing, main pages, and static pages.
- Inside src/app/api, there are API routes (note, uploadthing, webhook/clerk) that are used for server-side functionality and integrations.
- The presence of an /admin folder under src/app/(Content) shows the in-app admin panel secured through Clerk middleware.
- Other directories like src/server (containing db connections, queries, and utility functions) and src/lib (with markdown and schemas) outline the backend logic for database management and note handling.
- The separate components folder indicates reusable UI segments (e.g., header, footer, markdown-editor, UI components) that assemble the frontend.

##### Main Components
a. Frontend (Next.js Application)
- Pages: Landing, Main (with sub-components: dashboard, edit, note, new), Admin Panel, Authentication pages.
- Components: UI elements (buttons, dialogs, forms, markdown renderer, editor, and so on).
- Routing: App Router structure including public and protected routes.
b. Backend/API Layer:
- API Routes: note list, uploads via UploadThing, webhooks for Clerk.
- Server-side functionalities: Database access via Turso (SQLite), processing markdown (rendering and saving notes), rate limiting with Upstash.
- Middleware & User Management: Authentication and authorization using Clerk, with special routes and webhook integrations.
c. External Services:
- Authentication: Clerk service for sign in, user metadata, and administration roles.
- Storage/File management: UploadThing handling drag & drop file uploads.
- Database: Turso acting as a serverless SQLite DB for data storage, coordinated by the server (src/server/db).
- Analytics: PostHog capturing analytics events.
- Rate Limiting: Upstash service for preventing abuse and throttling requests.

##### Relationships and Interactions
- The frontend interacts with backend API endpoints for note management, file uploads, and webhooks.
- The authentication middleware (using Clerk) secures API routes and admin pages.
- Server components query/update the Turso database, such as inserting, selecting, updating, and deleting notes.
- Third-party service integrations (UploadThing, PostHog, Upstash) should be drawn as external services interfacing with the backend.
- Architectural patterns like separation of concerns (distinct layers for UI, business logic, data storage) should be highlighted.

##### Architectural Patterns and Design Principles
- MVC / Component-based design: The Next.js app follows a component-based model; the routes define views and the API routes provide the controllers.
- Separation between frontend (UI, pages, components) and backend (API routes, database logic, middleware) is clear.
- Extensibility: The use of modular folders (e.g., src/lib, src/server, src/components) suggests a design that is easily maintainable and scalable.
- Edge Computing: Inclusion of Turso indicates that database queries will be executed with edge computing considerations.

##### Elements
- Component Labels: Names like "Next.js App (Frontend)", "API Routes", "Authentication (Clerk)", "Database (Turso)", "File Storage (UploadThing)", "Analytics (PostHog)", "Rate Limiting (Upstash)".

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User Browser"]:::external

    %% Frontend (Next.js App)
    F0("Next.js App (Frontend)"):::frontend
    F1("Landing Pages"):::frontend
    F2("Main Pages"):::frontend
    F3("Admin Panel"):::frontend
    F4("Authentication Pages"):::frontend
    F5("UI Components"):::frontend
    F6("Markdown Editor"):::frontend
    F7("Markdown Renderer"):::frontend

    %% Backend / API Layer
    APIRoutes("API Routes"):::backend
    B1("Note API"):::backend
    %% UploadThing API as a sub-group
    subgraph "UploadThing API"
        B2a("Core"):::backend
        B2b("Route"):::backend
    end
    B3("Clerk Webhook API"):::backend

    %% Server-side Logic
    SL1("DB Connection & Schema"):::backend
    SL2("Queries"):::backend
    SL3("Markdown Processing"):::backend
    SL5("UploadThing Integration"):::backend
    SL6("User Management"):::backend
    SL7("Reports"):::backend
    DBOps("Database Operations"):::backend

    %% Library Utilities & Schemas
    Lib1("Markdown Functions"):::backend
    Lib2("Schemas"):::backend
    Lib3("Utils"):::backend

    %% External Services
    E1("Clerk Authentication"):::external
    E2("File Storage (UploadThing)"):::external
    E3("Database (Turso)"):::external
    E4("Analytics (PostHog)"):::external
    E5("Rate Limiting (Upstash)"):::external

    %% Connections: User & Frontend
    User --> F0
    F0 --> F1
    F0 --> F2
    F0 --> F3
    F0 --> F4
    F0 --> F5
    F5 --> F6
    F5 --> F7
    F0 --> APIRoutes

    %% Connections: API Routes and its child endpoints
    APIRoutes --> B1
    APIRoutes --> B2a
    APIRoutes --> B2b
    APIRoutes --> B3
    APIRoutes --> E4
    APIRoutes --> E5

    %% Connections: API Routes to Server-side Logic
    APIRoutes --> SL1
    APIRoutes --> SL2
    APIRoutes --> SL3
    APIRoutes --> SL5
    APIRoutes --> SL6
    APIRoutes --> SL7

    %% Server Logic to Database Operations
    SL1 --> DBOps
    SL2 --> DBOps
    DBOps --> E3

    %% External interactions from API endpoints
    B3 --> E1
    B2a --> E2
    B2b --> E2

    %% Library Utilities used by Server Logic
    SL3 --> Lib1
    SL3 --> Lib2
    SL3 --> Lib3

    %% Click Events for Frontend components
    click F0 "https://github.com/sleepy-gogo/coonspace/tree/main/src/app"
    click F1 "https://github.com/sleepy-gogo/coonspace/tree/main/src/app/(Content)/(Landing)"
    click F2 "https://github.com/sleepy-gogo/coonspace/tree/main/src/app/(Content)/(Main)"
    click F3 "https://github.com/sleepy-gogo/coonspace/tree/main/src/app/(Content)/admin"
    click F4 "https://github.com/sleepy-gogo/coonspace/tree/main/src/app/auth"
    click F5 "https://github.com/sleepy-gogo/coonspace/tree/main/src/components"
    click F6 "https://github.com/sleepy-gogo/coonspace/blob/main/src/components/markdown-editor.tsx"
    click F7 "https://github.com/sleepy-gogo/coonspace/blob/main/src/components/markdown-renderer.tsx"

    %% Click Events for API layer
    click B1 "https://github.com/sleepy-gogo/coonspace/blob/main/src/app/api/note/list/route.ts"
    click B2a "https://github.com/sleepy-gogo/coonspace/blob/main/src/app/api/uploadthing/core.ts"
    click B2b "https://github.com/sleepy-gogo/coonspace/blob/main/src/app/api/uploadthing/route.ts"
    click B3 "https://github.com/sleepy-gogo/coonspace/blob/main/src/app/api/webhook/clerk/route.ts"

    %% Click Events for Server-side logic
    click SL1 "https://github.com/sleepy-gogo/coonspace/tree/main/src/server/db"
    click SL2 "https://github.com/sleepy-gogo/coonspace/tree/main/src/server/queries"
    click SL3 "https://github.com/sleepy-gogo/coonspace/blob/main/src/server/markdown.ts"
    click SL5 "https://github.com/sleepy-gogo/coonspace/blob/main/src/server/uploadthing.ts"
    click SL6 "https://github.com/sleepy-gogo/coonspace/blob/main/src/server/users.ts"
    click SL7 "https://github.com/sleepy-gogo/coonspace/blob/main/src/server/report.ts"

    %% Click Events for Library Utilities
    click Lib1 "https://github.com/sleepy-gogo/coonspace/blob/main/src/lib/markdown.ts"
    click Lib2 "https://github.com/sleepy-gogo/coonspace/tree/main/src/lib/schemas"
    click Lib3 "https://github.com/sleepy-gogo/coonspace/blob/main/src/lib/utils.ts"

    %% Click for External Authentication mapping (Clerk types)
    click E1 "https://github.com/sleepy-gogo/coonspace/blob/main/src/types/clerk.d.ts"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
```
