Skip to content

README.md

Latest commit

 

History

History
146 lines (115 loc) · 8.48 KB

README.md

File metadata and controls

146 lines (115 loc) · 8.48 KB

Museum Management REST API

Node.js TypeScript Express PostgreSQL Drizzle ORM OpenAPI Zod WebSocket

Museum Management API

Production-ready REST API for a digital museum platform: content, auth, bookings, forum, and real-time features. Built with a modular, microservice-friendly design and standard Web API practices.

Key features

Capability Description
RESTful API design Versioned base path (/api/v1), standard HTTP verbs (GET, POST, PUT, PATCH, DELETE), appropriate status codes (2xx, 4xx, 5xx), and JSON request/response bodies aligned with Web API best practices.
Interactive API documentation OpenAPI 3.0 specification with Swagger UI at GET /api-docs and machine-readable spec at GET /api-docs.json for client generation and integration.
Structured error handling Consistent JSON error payloads with success, error.message, requestId, timestamp, and path; 404 responses for unknown routes and predictable error semantics across all endpoints.
Security & observability Helmet security headers, CORS policies, global and login-specific rate limiting, environment validation at startup, and health/live/ready probes for orchestration and monitoring.
Testable architecture App factory pattern decouples app creation from server binding; unit and integration tests with automated CI pipeline (lint, typecheck, test, build).

Tech stack

Layer Choice
Runtime Node.js 18+
Language TypeScript (strict)
Framework Express 4.x
Database PostgreSQL (local + Neon serverless)
ORM Drizzle ORM
Auth Passport.js (local), session-based
Validation Zod
Security Helmet, CORS, rate limiting
Real-time WebSocket (ws)

Architecture

  • Modular domains: Each feature (history, gallery, bookings, forum, contact, admin, auth, users) lives in its own routes/controllers/services so domains can be split into microservices later.
  • App factory: createApp() builds the Express app without starting the server for testability and clean process boundaries.
  • Env-first: Config validated at startup via Zod; invalid env fails fast.
  • Structured errors: Custom AppError types (e.g. NotFoundError, ValidationError) with correct HTTP status and consistent JSON error payloads including requestId.

API base

All endpoints are under /api/v1 (e.g. GET /api/v1/health).

Area Examples
Health GET /api/v1/health
Auth POST /api/v1/auth/register, POST /api/v1/auth/login, GET /api/v1/auth/profile
History GET /api/v1/histories, GET /api/v1/histories/:id, POST /api/v1/histories (admin)
Gallery GET /api/v1/gallery, GET /api/v1/gallery/category/:category
Bookings GET /api/v1/bookings, POST /api/v1/bookings
Forum GET /api/v1/forum/posts, POST /api/v1/forum/posts, POST /api/v1/forum/likes
Contact POST /api/v1/contact
Admin Admin-only routes under /api/v1/admin
WebSocket /ws on same server

Responses use a consistent shape: { success, data?, error?, message?, pagination?, requestId? }. Errors include requestId and timestamp.

Quick start

Requirements: Node.js 18+, pnpm 8+

git clone <repo-url>
cd repo_name
pnpm install
cp .env.example .env   # then set DATABASE_URL, SESSION_SECRET, FRONTEND_URL, etc.
pnpm run db:push       # or db:migrate
pnpm run dev           # http://localhost:5001

Important env vars

Variable Description
DATABASE_URL PostgreSQL URL (dev)
DATABASE_URL_PROD Production DB (e.g. Neon)
SESSION_SECRET Min 32 chars
FRONTEND_URL Allowed CORS origin (default http://localhost:3000)
CORS_ORIGINS Optional comma-separated extra origins
PORT Server port (default 5001)

Scripts

Command Purpose
pnpm run dev Dev server with hot reload
pnpm run build / pnpm start Production build and run
pnpm run check TypeScript check
pnpm run test Unit + integration tests (includes CORS tests)
pnpm run lint ESLint
pnpm run db:push / db:migrate / db:seed Database

Security & performance

  • CORS: Env-based allowed origins (no wildcard when using credentials); preflight and headers tested.
  • Helmet: Security headers (CSP, HSTS, etc.).
  • Rate limiting: Applied on login and sensitive routes.
  • Request tracing: X-Request-ID on every response; structured logging with request IDs.
  • Health: /api/v1/health returns DB status and version; 503 when DB is down.

Testing

  • Unit tests for services (e.g. history service).
  • CORS tests: allowed origin gets Access-Control-Allow-Origin, preflight returns 204, disallowed origin rejected.
  • Run: pnpm test.

Deployment

  • Build: pnpm run build then node dist/index.js (or pnpm start).
  • Set NODE_ENV=production, DATABASE_URL_PROD, API_PROD_URL, and a strong SESSION_SECRET.
  • Suitable for Node hosts (e.g. Render, Railway, Fly.io).

Project structure

├── app.ts                 # Express app factory (no server listen)
├── index.ts               # Entry: env, createApp, registerRoutes, listen
├── config/                # Env, auth, CORS, DB, OpenAPI, security
├── middlewares/           # Request ID, rate limit, errors, not-found
├── server/
│   ├── routes/            # Route modules mounted under /api/v1
│   ├── controllers/       # Request/response handling
│   ├── services/          # Business logic
│   └── types/             # API response types
├── docs/                  # Feature summary, architecture notes
└── drizzle/               # Migrations

License

MIT.