# yu62ballena/my-pocket architecture

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

- Interactive diagram: https://gitdiagram.com/yu62ballena/my-pocket
- Repository: https://github.com/yu62ballena/my-pocket

## Overview

##### Project Type & Purpose
- This is a full-stack, server‐centric web app built with Next.js.
- It provides a UI for users to save, categorize, like, archive, and search articles by URL; it extracts metadata from submitted URLs.
- Authentication is handled by NextAuth, and data persistence is done via Prisma/PostgreSQL.

##### File Structure
- `app/` – Next.js “app router” directory.
- `app/page.tsx`, `app/layout.tsx`, `app/providers.tsx` — root layout, providers (e.g. SessionProvider).
- `app/components/…` — UI components (cards, buttons, sidebar, forms, etc.).
- `app/actions/…` — server actions that encapsulate business logic (CRUD on articles/categories, metadata extraction).
- `app/api/…` — route handlers (e.g. NextAuth endpoints, RESTful save‐article API).
- `app/save`, `app/signin`, etc. — page directories for individual routes.
- `lib/` — shared helpers (authentication, Prisma client, input validation).
- `prisma/` — migrations and schema for PostgreSQL.
- `hooks/` — React hooks for infinite scroll, form submission, article loading.
- `public/` — static assets (PWA manifest, service worker).
- `constants/`, `types/` — well-typed constants and TypeScript declarations.

##### README for Technical Stack
- Next.js App Router (React, SSR, server actions)
- next/font for optimized fonts
- NextAuth for authentication
- Prisma ORM for DB access
- Deployed on Vercel (implied)

##### Main Components & Their Relationships
A. Client (Browser/PWA)
- Renders React UI components (in `app/components`).
- Submits data via server actions (form submissions) or fetch calls to `app/api` routes.
- Holds Service Worker (in `public/sw.js`) for offline caching.
B. Next.js Server (Server-Side)
- App Router entrypoint: handles routing, SSR/SSG, server actions (`app/actions`).
- API Routes: NextAuth endpoints (`app/api/auth/[...nextauth]`), custom REST endpoints (`app/api/save-article`).
- Invokes business logic modules in `lib/` (auth-helpers, validations).
C. Authentication Provider
- NextAuth uses OAuth / email providers (external, e.g., Google/GitHub).
- Session state passed into React via `SessionProvider` (in `app/providers.tsx`).
D. Database
- Prisma Client (`lib/prisma.ts`) connects to PostgreSQL (defined in `prisma/schema.prisma` + migrations).
- Article and category tables, with relations / timestamps / published-at fields.
E. External Metadata Service
- The server action `app/actions/extract-url-data.ts` makes HTTP requests to fetch page titles, images, etc.

##### Architectural Patterns & Design Principles
- Full-stack React/Next.js (Server Actions for mutation logic, API routes for REST).
- Separation of concerns: UI (components/hooks) vs. business logic (`app/actions`, `lib/`) vs. data layer (Prisma).
- Strong typing (TypeScript) & validation at boundary (`lib/validations`).
- PWA features (manifest, service worker).
- MVC‐ish flow:
Browser → Controller (server actions/API) → Model (Prisma/DB) → Response → View (React).

##### Elements
- Clear component labels: “Next.js App Router”, “Server Actions”, “API Routes”, “Prisma Client”, “PostgreSQL DB”, “OAuth Provider”, “Browser UI”, “Service Worker”.
- Persistence (orange),
- External (gray).
- Arrowheads indicating data flow and direction.
- Annotations for key modules: e.g., `app/actions/articles/...`, `lib/auth-helpers.ts`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser/PWA)"
        direction TB
        UI["UI Components"]:::client
        click UI "https://github.com/yu62ballena/my-pocket/tree/main/app/components/"
        PageLayout["Page Layout & Providers"]:::client
        click PageLayout "https://github.com/yu62ballena/my-pocket/blob/main/app/page.tsx"
        click PageLayout "https://github.com/yu62ballena/my-pocket/blob/main/app/layout.tsx"
        click PageLayout "https://github.com/yu62ballena/my-pocket/blob/main/app/providers.tsx"
        SavePage["Save Page Route"]:::client
        click SavePage "https://github.com/yu62ballena/my-pocket/blob/main/app/save/page.tsx"
        SignInPage["SignIn Page Route"]:::client
        click SignInPage "https://github.com/yu62ballena/my-pocket/blob/main/app/signin/page.tsx"
        Hooks["React Hooks"]:::client
        click Hooks "https://github.com/yu62ballena/my-pocket/tree/main/hooks/"
        SW["Service Worker & PWA Manifest"]:::client
        click SW "https://github.com/yu62ballena/my-pocket/blob/main/public/sw.js"
        click SW "https://github.com/yu62ballena/my-pocket/blob/main/public/manifest.json"
    end

    %% Server Layer
    subgraph "Next.js Server"
        direction TB
        AppRouter["Next.js App Router"]:::server
        ServerActions["Server Actions"]:::server
        subgraph "Articles Actions"
            direction TB
            CDup["check-duplicate.ts"]:::server
            click CDup "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/check-duplicate.ts"
            DelArt["delete-article.ts"]:::server
            click DelArt "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/delete-article.ts"
            GArt["get-articles.ts"]:::server
            click GArt "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/get-articles.ts"
            GSite["get-sitedata.ts"]:::server
            click GSite "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/get-sitedata.ts"
            RQ["redirect-with-query.ts"]:::server
            click RQ "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/redirect-with-query.ts"
            SArt["save-article.ts"]:::server
            click SArt "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/save-article.ts"
            SSearch["search-articles.ts"]:::server
            click SSearch "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/search-articles.ts"
            TArch["toggle-archive.ts"]:::server
            click TArch "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/toggle-archive.ts"
            TLike["toggle-like.ts"]:::server
            click TLike "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/articles/toggle-like.ts"
        end
        subgraph "Category Actions"
            direction TB
            CCreate["create-category.ts"]:::server
            click CCreate "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/categories/create-category.ts"
            CDel["delete-category.ts"]:::server
            click CDel "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/categories/delete-category.ts"
            CGet["get-categories.ts"]:::server
            click CGet "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/categories/get-categories.ts"
            CUpd["update-category.ts"]:::server
            click CUpd "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/categories/update-category.ts"
        end
        ExtMeta["extract-url-data.ts"]:::server
        click ExtMeta "https://github.com/yu62ballena/my-pocket/blob/main/app/actions/extract-url-data.ts"
        APIRoutes["API Routes"]:::server
        subgraph "NextAuth & Custom APIs"
            direction TB
            NextAuthRoute["[...nextauth]/route.ts"]:::server
            click NextAuthRoute "https://github.com/yu62ballena/my-pocket/blob/main/app/api/auth/[...nextauth]/route.ts"
            AuthStatus["auth/status/route.ts"]:::server
            click AuthStatus "https://github.com/yu62ballena/my-pocket/blob/main/app/api/auth/status/route.ts"
            SaveAPI["save-article/route.ts"]:::server
            click SaveAPI "https://github.com/yu62ballena/my-pocket/blob/main/app/api/save-article/route.ts"
        end
    end

    %% Business Logic & Helpers
    subgraph "Lib / Helpers / Config"
        direction TB
        AuthHelpers["Auth Helpers & Config"]:::server
        click AuthHelpers "https://github.com/yu62ballena/my-pocket/blob/main/lib/auth-helpers.ts"
        click AuthHelpers "https://github.com/yu62ballena/my-pocket/blob/main/lib/auth.ts"
        Validations["Input Validations"]:::server
        click Validations "https://github.com/yu62ballena/my-pocket/blob/main/lib/validations/search-validation.ts"
        click Validations "https://github.com/yu62ballena/my-pocket/blob/main/lib/validations/url-validation.ts"
        PrismaClient["Prisma Client"]:::data
        click PrismaClient "https://github.com/yu62ballena/my-pocket/blob/main/lib/prisma.ts"
    end

    %% Persistence Layer
    subgraph "Database (PostgreSQL)"
        direction TB
        Schema["Schema & Migrations"]:::data
        click Schema "https://github.com/yu62ballena/my-pocket/blob/main/prisma/schema.prisma"
        click Schema "https://github.com/yu62ballena/my-pocket/tree/main/prisma/migrations/"
        DB["PostgreSQL DB"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["OAuth Provider"]:::external
        MetaService["External Metadata Service"]:::external
    end

    %% Data Flows
    UI -->|"Server Action Call"| ServerActions
    UI -->|"Fetch/API Call (HTTP)"| APIRoutes
    UI -->|"Service Worker Caching"| SW
    AppRouter -->|"invokes"| ServerActions
    AppRouter -->|"routes to"| APIRoutes
    ServerActions -->|"uses"| AuthHelpers
    ServerActions -->|"uses"| Validations
    ServerActions -->|"calls"| PrismaClient
    APIRoutes -->|"uses"| AuthHelpers
    APIRoutes -->|"queries"| PrismaClient
    PrismaClient -->|"SQL Queries"| DB
    ExtMeta -->|"HTTP Request"| MetaService
    NextAuthRoute -->|"OAuth Flow"| OAuth
    AuthStatus -->|"Session Query"| DB
    OAuth -->|"Callback"| NextAuthRoute

    %% Classes
    classDef client fill:#D0E8FF,stroke:#005B99,stroke-width:1px;
    classDef server fill:#D0FFD6,stroke:#0A8A0A,stroke-width:1px;
    classDef data fill:#FFE8B0,stroke:#B37500,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#666666,stroke-width:1px;
```
