TechHub: System Documentation

Amadeus — Sat, 25 Apr 2026 15:39:24 +0000

TechHub is a professional tech news and bookmark management platform. This guide covers the architecture, API reference, and setup procedures for developers.

System Overview TechHub is a full-stack web application built with Next.js 15 (App Router). It serves as a proxy for the Hacker News Firebase API and allows users to manage bookmarks in a local SQLite database using Prisma ORM. 1.1 Technology Stack Framework: Next.js (App Router) v16.x for SSR and routing. Language: TypeScript v5.x for type safety across all layers. Database: SQLite via Prisma ORM v5.x. Validation: Zod v3.x for schema validation on all API endpoints. Styling: TailwindCSS v4.x. Runtime: Node.js 20+. 1.2 Architecture & External Dependencies The application follows a three-tier architecture within a single Next.js deployment: Presentation Layer: React client components using fetch() to call internal API routes. Application Layer: Next.js Route Handlers handling HTTP requests and Zod validation. Data Layer: Prisma Client executing type-safe queries against prisma/dev.db. External API Integration: The Hacker News Firebase REST API is called server-side via /api/news. No API key is required, and responses are cached for 5 minutes (300 seconds) using Next.js fetch revalidation.
Database Schema 2.1 Bookmark Model id: String (Primary Key, cuid). title: String (Required article headline). url: String (Required, must be unique per bookmark). description/imageUrl/publishedAt/note: Optional fields for metadata and private user notes. source: String (Origin, typically 'Hacker News'). categoryId: Foreign Key to Category (Nullable). 2.2 Category Model id: String (Primary Key, cuid). name: String (Unique, required, 1–50 chars). color: String (Required hex color string). Relation: One Category has many Bookmarks. Deleting a category setscategoryId to NULL for all related bookmarks.
API Reference 3.1 News Proxy GET /api/news: Fetches and normalizes stories from Hacker News. Params: type (top|new|best), limit (max 50). 3.2 Bookmarks GET /api/bookmarks: Returns an array of bookmarks; supports categoryId filtering. POST /api/bookmarks: Creates a new bookmark using the BookmarkCreate schema. PATCH /api/bookmarks/🆔 Updates existing bookmark notes or category. DELETE /api/bookmarks/🆔 Removes a bookmark record. 3.3 Categories GET /api/categories: Returns all categories with a count of related bookmarks. POST /api/categories: Creates a new category. PUT /api/categories/🆔 Updates category details. DELETE /api/categories/🆔 Deletes the category and unlinks associated bookmarks.
Setup & Deployment 4.1 Initial Setup npm install: Install Node.js dependencies. cp .env.example .env: Create environment configuration. npx prisma generate: Compile Prisma Client from the schema. npx prisma db push: Create the SQLite database and tables. npm run dev: Start the development server on port 3000. 4.2 Production Build npx prisma generate: Regenerate client for production. npx prisma db push: Apply schema to the production database. npm run build: Compile and optimize the application. npm run start: Start the production server. Note: The SQLite file (prisma/dev.db) is created automatically. For production, ensure this file is on a persistent volume.
Security & Error Handling Input Validation: All write operations are validated server-side using Zod. SQL Injection: Mitigated via Prisma's parameterized queries. Error Responses: Standardized JSON format containing a human-readable error message and field-level details. 400 Bad Request: Validation failed. 409 Conflict: Duplicate URL or Category Name. 500 Internal Server Error: Database or unexpected exceptions.

DEV Community: Amadeus

TechHub: System Documentation