# laeekahmed/notespot architecture

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

- Interactive diagram: https://gitdiagram.com/laeekahmed/notespot
- Repository: https://github.com/laeekahmed/notespot

## Overview

##### Project type and purpose
- This is a full-stack, cloud-native file management platform (“Notespot”) with:
- A Next.js frontend deployed on Vercel.
- An Express.js REST API running on AWS Lambda (Serverless Framework).
- Public & private file sharing via AWS S3 presigned URLs.
- Authentication handled by Clerk.
- Metadata stored in MongoDB Atlas.
- Logging in CloudWatch.

##### File structure
- Top-level “frontend” folder: Next.js 13 app (app directory, components, hooks, lib, UI primitives).
- Top-level “backend” folder: Express server entry (index.ts), Lambda wrapper (lambda.ts), Serverless config, models, migrations, routes (authors, documents), utils (auth, logger, metrics), config, and TS setup.
- CI/CD: .github/workflows/deploy.yml.
- Environment examples in both frontend/.env.example and backend/.env.example.

##### Pull additional insights from the README
- Confirms deployment targets (Vercel, AWS Lambda via Serverless Framework).
- Highlights key integrations: Clerk (auth), S3 (file storage), MongoDB Atlas (database), CloudWatch (logging).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        User["User Browser"]:::frontend
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        NextFrontend["Next.js Frontend<br/>(Vercel)"]:::frontend
        APIClient["API Client<br/>(lib/api.ts)"]:::frontend
        UseDebounce["useDebounce Hook"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
        FrontMiddleware["Frontend Middleware"]:::frontend
    end

    %% Auth Layer
    subgraph "Auth Layer"
        Clerk["Clerk (Auth Service)"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        APIGW["API Gateway"]:::compute
        LambdaWrapper["Lambda Wrapper"]:::compute
        ExpressAPI["Express.js REST API"]:::compute
        AuthorsRoutes["Authors Routes"]:::compute
        DocumentsRoutes["Documents Routes"]:::compute
        AuthUtil["Auth Utility"]:::compute
        S3Helpers["S3 Helpers"]:::compute
        LoggerUtil["Logger Utility"]:::compute
        MetricsUtil["Metrics Utility"]:::compute
    end

    %% Data Layer
    subgraph "Data Layer"
        MongoDB["MongoDB Atlas"]:::data
        S3["AWS S3 Bucket"]:::data
    end

    %% Observability
    subgraph "Observability"
        CloudWatch["AWS CloudWatch"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        CICD["GitHub Actions"]:::external
    end

    %% Connections
    User -->|"Interacts via UI"| NextFrontend
    NextFrontend -->|"uses Middleware"| FrontMiddleware
    NextFrontend -->|"calls API"| APIGW
    NextFrontend -->|"fetch auth"| Clerk
    NextFrontend -->|"direct file transfer"| S3

    APIGW -->|"invokes"| LambdaWrapper
    LambdaWrapper -->|"wraps"| ExpressAPI
    ExpressAPI -->|"routes to"| AuthorsRoutes
    ExpressAPI -->|"routes to"| DocumentsRoutes
    ExpressAPI -->|"validates JWT via"| AuthUtil
    ExpressAPI -->|"generates presigned URL via"| S3Helpers
    ExpressAPI -->|"queries/updates"| MongoDB
    ExpressAPI -->|"emits logs via"| LoggerUtil

    LoggerUtil -.->|"push logs"| CloudWatch
    MetricsUtil -.->|"collect metrics"| CloudWatch

    CICD -->|"deploys Frontend"| NextFrontend
    CICD -->|"deploys Backend"| LambdaWrapper

    %% Click Events - Frontend
    click NextFrontend "https://github.com/laeekahmed/notespot/tree/main/frontend/"
    click APIClient "https://github.com/laeekahmed/notespot/blob/main/frontend/src/lib/api.ts"
    click UseDebounce "https://github.com/laeekahmed/notespot/blob/main/frontend/src/hooks/useDebounce.ts"
    click UIPrimitives "https://github.com/laeekahmed/notespot/tree/main/frontend/src/components/ui/"
    click FrontMiddleware "https://github.com/laeekahmed/notespot/blob/main/frontend/src/middleware.ts"
    click NextFrontend "https://github.com/laeekahmed/notespot/blob/main/frontend/next.config.mjs"
    click NextFrontend "https://github.com/laeekahmed/notespot/blob/main/frontend/.env.example"
    click NextFrontend "https://github.com/laeekahmed/notespot/blob/main/frontend/tailwind.config.ts"

    %% Click Events - Backend
    click LambdaWrapper "https://github.com/laeekahmed/notespot/blob/main/backend/lambda.ts"
    click ExpressAPI "https://github.com/laeekahmed/notespot/blob/main/backend/index.ts"
    click CICD "https://github.com/laeekahmed/notespot/blob/main/.github/workflows/deploy.yml"
    click AuthorsRoutes "https://github.com/laeekahmed/notespot/blob/main/backend/routes/api/authors.ts"
    click DocumentsRoutes "https://github.com/laeekahmed/notespot/blob/main/backend/routes/api/documents.ts"
    click AuthUtil "https://github.com/laeekahmed/notespot/blob/main/backend/utils/auth.ts"
    click S3Helpers "https://github.com/laeekahmed/notespot/blob/main/backend/utils/helpers.ts"
    click LoggerUtil "https://github.com/laeekahmed/notespot/blob/main/backend/utils/logger.ts"
    click MetricsUtil "https://github.com/laeekahmed/notespot/blob/main/backend/utils/metrics.ts"
    click ExpressAPI "https://github.com/laeekahmed/notespot/blob/main/backend/serverless.yml"
    click ExpressAPI "https://github.com/laeekahmed/notespot/blob/main/backend/tsconfig.json"
    click ExpressAPI "https://github.com/laeekahmed/notespot/blob/main/backend/.env.example"
    click ExpressAPI "https://github.com/laeekahmed/notespot/blob/main/backend/config/env.ts"
    click MongoDB "https://github.com/laeekahmed/notespot/blob/main/backend/models/document.ts"
    click MongoDB "https://github.com/laeekahmed/notespot/blob/main/backend/migrations/add-shortId.ts"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#1E3A8A,color:#1E3A8A;
    classDef compute fill:#DCFCE7,stroke:#166534,color:#166534;
    classDef data fill:#FFEDD5,stroke:#C2410C,color:#C2410C;
    classDef external fill:#F3E8FF,stroke:#6B21A8,color:#6B21A8;
```
