# aces-rmdssoe/share architecture

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

- Interactive diagram: https://gitdiagram.com/aces-rmdssoe/share
- Repository: https://github.com/aces-rmdssoe/share

## Overview

##### Project type and purpose
- This is a full-stack Next.js application with serverless API routes, a MongoDB backend, and QR-code generation.
- Purpose: shorten URLs, generate QR codes, and provide an admin dashboard with analytics.

##### File structure
- Top-level folders:
- pages/      → Next.js routing (UI pages + serverless API endpoints under pages/api)
- components/ → React components and dialogs
- lib/, models/ → shared utilities and Mongoose models
- docs/       → contribution guidelines and architecture overview
- Key config files: next.config.js, tailwind.config.js, tsconfig.json
- Build/deploy: relies on Vercel (or any Node-capable host) to run Next.js SSR/SSG and API lambdas.

##### Extract additional insights from the README
- Two main user flows:
a. Public: shorten a URL + produce QR code
b. Admin: view dashboard, manage links, see analytics (page views, recent accesses, CSV export)
- Tech stack: Next.js (React + SSR), TypeScript, MongoDB, Tailwind CSS, Sonner notifications.

- Client (Browser/Mobile)
- Next.js Frontend (React pages)
- Next.js API Layer (serverless functions under pages/api)
- MongoDB Atlas (NoSQL database)
- QR-code Generator Library (internal node module or external service if applicable)
- External Analytics Export (CSV generation)
- Optional: CDN/static hosting for public/ assets
1. Client → HTTP(S) → Next.js Frontend (pages/index.tsx, pages/[shortUrl].tsx, pages/analytics.tsx)
2. Frontend → AJAX/fetch → API Layer (/api/shorten, /api/analytics, /api/authenticate, etc.)
3. API Layer → MongoDB (CRUD operations via src/models/url.ts & lib/utils/db.ts)
4. API Layer → QR-code module → returns image/JSON to Frontend
5. Analytics page → API fetch → MongoDB → Frontend visualization
6. CSV export endpoint → generates CSV (pages/api/csvAnalytics.ts) → Client download
c. Architectural patterns / design principles:
- Serverless microservices: each API route is a discrete Lambda
- Component-based UI: reusable React components & hooks
- Separation of concerns: UI vs logic (lib/utils) vs data (models)
- Environments: .env for secrets (Mongo URI, auth tokens)
- Next.js (SSR/SSG, API Routes)
- React + TypeScript
- MongoDB Atlas + Mongoose (or native driver)
- QRCode.js or similar library
- Tailwind CSS
- Sonner for notifications

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser/Mobile)" 
        direction TB
        Client["Client"]:::client
    end

    %% Frontend Layer
    subgraph "Next.js Frontend" 
        direction TB
        IndexPage["pages/index.tsx"]:::frontend
        ShortPage["pages/[shortUrl].tsx"]:::frontend
        AnalyticsPage["pages/analytics.tsx"]:::frontend
        GraphsPage["pages/graphs.tsx"]:::frontend
        SharePage["pages/share.tsx"]:::frontend
        QRCustomize["components/qrcustomize.tsx"]:::frontend
        QRCodeDialog["components/dialogs/qrcodeDialog.tsx"]:::frontend
        AuthHook["hooks/useAuthen.ts"]:::frontend
    end

    %% Admin Components
    subgraph "Admin Dashboard Components" 
        direction TB
        SortComp["components/analyticsSort.tsx"]:::frontend
        HeaderComp["components/visualizeHeader.tsx"]:::frontend
        GraphDialog["components/dialogs/graphDialog.tsx"]:::frontend
        RecentComp["components/dialogs/recentAccesses.tsx"]:::frontend
    end

    %% API Layer
    subgraph "Next.js API Layer" 
        direction TB
        ShortenAPI["/api/shorten"]:::api
        AnalyticsAPI["/api/analytics"]:::api
        AuthAPI["/api/authenticate"]:::api
        CSVAPI["/api/csvAnalytics"]:::api
        SearchDialogAPI["/api/searchDialogPages"]:::api
    end

    %% Data & Utils
    DB["MongoDB Atlas"]:::db
    DBUtils["lib/utils/db.ts"]:::utils
    URLModel["models/url.ts"]:::utils
    Utils["lib/utils/utils.ts"]:::utils

    %% Static Assets
    subgraph "CDN / Static Assets" 
        direction TB
        Images["public/images"]:::external
        Public["public"]:::external
    end

    %% Client to Frontend
    Client -->|HTTP GET| IndexPage
    Client -->|HTTP GET| ShortPage
    Client -->|HTTP GET| AnalyticsPage
    Client -->|HTTP GET| GraphsPage
    Client -->|HTTP GET| SharePage

    %% Frontend to API
    IndexPage -->|fetch /api/shorten| ShortenAPI
    ShortPage -->|redirect| ShortenAPI
    AnalyticsPage -->|fetch /api/analytics| AnalyticsAPI
    AnalyticsPage -->|fetch /api/csvAnalytics| CSVAPI
    GraphsPage -->|fetch /api/searchDialogPages| SearchDialogAPI
    AuthHook -->|calls| AuthAPI

    %% Frontend Components Usage
    IndexPage --> QRCustomize
    IndexPage --> QRCodeDialog
    AnalyticsPage --> SortComp
    AnalyticsPage --> HeaderComp
    AnalyticsPage --> GraphDialog
    AnalyticsPage --> RecentComp

    %% API to Data Layer
    ShortenAPI -->|CRUD| DBUtils
    AnalyticsAPI -->|CRUD| DBUtils
    CSVAPI -->|CRUD| DBUtils
    AuthAPI -->|CRUD| DBUtils
    SearchDialogAPI -->|CRUD| DBUtils

    DBUtils --> URLModel
    DBUtils --> DB

    %% Static assets serving
    Client -->|GET static| Images
    Client -->|GET static| Public

    %% Click Events
    click IndexPage "https://github.com/aces-rmdssoe/share/blob/main/src/pages/index.tsx"
    click ShortPage "https://github.com/aces-rmdssoe/share/blob/main/src/pages/[shortUrl].tsx"
    click AnalyticsPage "https://github.com/aces-rmdssoe/share/blob/main/src/pages/analytics.tsx"
    click GraphsPage "https://github.com/aces-rmdssoe/share/blob/main/src/pages/graphs.tsx"
    click SharePage "https://github.com/aces-rmdssoe/share/blob/main/src/pages/share.tsx"
    click ShortenAPI "https://github.com/aces-rmdssoe/share/blob/main/src/pages/api/shorten.ts"
    click AnalyticsAPI "https://github.com/aces-rmdssoe/share/blob/main/src/pages/api/analytics.ts"
    click AuthAPI "https://github.com/aces-rmdssoe/share/blob/main/src/pages/api/authenticate.ts"
    click CSVAPI "https://github.com/aces-rmdssoe/share/blob/main/src/pages/api/csvAnalytics.ts"
    click SearchDialogAPI "https://github.com/aces-rmdssoe/share/blob/main/src/pages/api/searchDialogPages.ts"
    click DBUtils "https://github.com/aces-rmdssoe/share/blob/main/src/lib/utils/db.ts"
    click URLModel "https://github.com/aces-rmdssoe/share/blob/main/src/models/url.ts"
    click QRCodeDialog "https://github.com/aces-rmdssoe/share/blob/main/src/components/dialogs/qrcodeDialog.tsx"
    click QRCustomize "https://github.com/aces-rmdssoe/share/blob/main/src/components/qrcustomize.tsx"
    click SortComp "https://github.com/aces-rmdssoe/share/blob/main/src/components/analyticsSort.tsx"
    click HeaderComp "https://github.com/aces-rmdssoe/share/blob/main/src/components/visualizeHeader.tsx"
    click GraphDialog "https://github.com/aces-rmdssoe/share/blob/main/src/components/dialogs/graphDialog.tsx"
    click RecentComp "https://github.com/aces-rmdssoe/share/blob/main/src/components/dialogs/recentAccesses.tsx"
    click AuthHook "https://github.com/aces-rmdssoe/share/blob/main/src/hooks/useAuthen.ts"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef frontend fill:#C8FACC,stroke:#333,stroke-width:1px
    classDef api fill:#A0D8EF,stroke:#333,stroke-width:1px
    classDef db fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef utils fill:#F0D0FF,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
