How yu62ballena/my-pocket works
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.