Scribe Server

The backend/server for the Scribe application built with Hono and OpenAPI. This is a fully documented, type-safe JSON API with automatic OpenAPI documentation generation.

• Tech Stack
• Setup
• Development
• Code Tour
• API Endpoints
• Contributing
• References

Tech Stack

Core Framework

• Hono - Fast, lightweight web framework
• @hono/zod-openapi - OpenAPI 3.0 integration with Zod validation
• TypeScript - Type-safe development

Database & ORM

• Drizzle ORM - Type-safe ORM with PostgreSQL support
• drizzle-zod - Zod schema generation from database tables
• PostgreSQL - Primary database

Validation & Schemas

• Zod - Runtime type validation and schema definition
• drizzle-zod - Database schema to Zod schema conversion

Documentation

• Scalar - Interactive API documentation
• OpenAPI 3.0 - Automatic API specification generation

Development Tools

• Vitest - Fast unit testing framework
• ESLint with @antfu/eslint-config - Code linting
• Prettier - Code formatting
• pino - Structured logging

Utilities

• stoker - OpenAPI helpers and utilities
• tsx - Fast TypeScript execution

Authentication & Security

• Auth0 - Authentication and authorization platform
• jose - JWT verification and JWKS support

📚 Documentation

• Developer Documentation - Complete guides for API development
• Auth0 Integration Guide - How to create protected routes
• Quick Reference - Common patterns and examples

Setup

1. Clone and install dependencies:

   git clone <repository-url>
   cd scribe-server
   npm install

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your database credentials

   Required environment variables:

   NODE_ENV=development
   PORT=9999
   LOG_LEVEL=info
   DATABASE_URL=postgresql://user:password@localhost:5432/dbname
   AUTH0_DOMAIN=your-tenant.auth0.com
   AUTH0_AUDIENCE=http://localhost:9999

3. Set up a local database:

   Install Postgres locally, create a database, and update your .env:

   DATABASE_URL=postgresql://user:password@localhost:5432/scribe_dev

4. Run database migrations:

   npm run db:migrate

5. Start development server:

   npm run dev

6. View API documentation:

   • Open http://localhost:9999/reference for interactive API docs
   • Open http://localhost:9999/doc for OpenAPI specification

Development

# Development server with hot reload
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Code formatting
npm run format
npm run format:check

# Testing
npm run test
npm run test --watch

# Build for production
npm run build

# Production server
npm run start

# Database
npm run db:migrate            # Apply pending migrations
npm run db:generate <name>    # Generate a new named migration
npm run db:studio             # Open Drizzle Studio

Code Tour

Project Structure

src/
├── routes/              # OpenAPI route definitions
├── handlers/            # Business logic handlers
├── db/                  # Database schema and configuration
├── lib/                 # Utility functions and configuration
├── middlewares/         # Custom middleware
├── server/              # Server configuration
├── test/                # Test utilities
├── app.ts               # Main application setup
├── index.ts             # Application entry point
└── env.ts               # Environment configuration

Key Files

• index.ts - Application entry point using @hono/node-server
• app.ts - Main Hono application setup and OpenAPI configuration
• env.ts - Environment variable validation with Zod
• src/server/server.ts - Base server configuration with middleware
• src/db/schema.ts - Database schema definitions with Drizzle
• src/lib/configure-open-api.ts - OpenAPI documentation setup

Architecture Pattern

The project follows a route-handler architecture:

1. Routes (src/routes/) - Define OpenAPI routes with validation schemas
2. Handlers (src/handlers/) - Contain business logic and database operations
3. Database (src/db/) - Schema definitions and database connection
4. Utilities (src/lib/) - Shared utilities and configuration

Example Implementation

The project includes a complete Tasks feature implementation demonstrating the architecture. See the following files for reference:

• Database Schema: src/db/schema.ts - Table definitions and Zod validation schemas
• Handler Functions: src/handlers/task.handler.ts - Business logic and database operations
• Route Definitions: src/routes/task.route.ts - OpenAPI route specifications
• Tests: src/handlers/task.handler.test.ts - Handler testing patterns

API Endpoints

Public Endpoints

Method	Path	Description
GET	/	API Index
GET	/health	Health Check
GET	/doc	OpenAPI Specification
GET	/reference	Scalar API Documentation
GET	/api/public	Public data (no auth)

Protected Endpoints (Require Auth0 JWT)

Method	Path	Description
GET	/api/protected	Protected user data

Task Management (Examples)

Method	Path	Description
GET	/tasks	List all tasks
POST	/tasks	Create a task
GET	/tasks/{id}	Get one task by id
PATCH	/tasks/{id}	Update one task by id
DELETE	/tasks/{id}	Delete one task by id

Contributing

Please read CONTRIBUTING.md for detailed information about:

• Project architecture and patterns
• Adding new features
• Testing guidelines
• Code style and conventions
• Pull request process

References

Core Technologies

• Hono Documentation
• Drizzle ORM Documentation
• Zod Documentation
• Vitest Documentation

OpenAPI & Documentation

• What is OpenAPI?
• @hono/zod-openapi
• Scalar Documentation

Development Tools

• ESLint Antfu Config
• Stoker Utilities