readoft.blog

Modern blog platform built with TypeScript, Next.js, GraphQL Yoga, Prisma, and PostgreSQL.

🚀 Quick Start

Prerequisites

• Node.js ≥ 20.0.0
• pnpm ≥ 9.0.0
• Docker & Docker Compose

Installation

# Install dependencies
pnpm install -w

# Start local services (PostgreSQL, Memcached, MinIO, MailHog)
docker compose up -d

# Set up environment variables
cp apps/api/.env.example apps/api/.env

# Run database migrations
pnpm prisma:generate
pnpm prisma:migrate

# Seed the database with test data
pnpm db:seed

# Start development servers
pnpm dev

The web app will be available at http://localhost:3000 and the GraphQL API at http://localhost:4000/graphql.

📁 Project Structure

readoft-blog/
├── apps/
│   ├── web/              # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/      # Next.js App Router
│   │   │   ├── components/
│   │   │   └── lib/
│   │   └── package.json
│   └── api/              # GraphQL Yoga backend
│       ├── src/
│       │   ├── core/     # Schema, context, resolvers
│       │   └── adapters/ # External services
│       ├── prisma/
│       │   ├── schema.prisma
│       │   └── seed.ts
│       └── package.json
├── packages/
│   ├── ui/               # Shared UI components
│   └── config/           # Shared configs
├── docs/                 # Documentation
├── scripts/              # Automation scripts
└── compose.yaml          # Docker services

🛠️ Development

Available Commands

# Development
pnpm dev:web              # Start Next.js dev server
pnpm dev:api              # Start GraphQL API dev server
pnpm dev                  # Start both concurrently

# Build
pnpm build                # Build all packages

# Code Quality
pnpm lint                 # Run ESLint
pnpm format               # Check Prettier formatting
pnpm format:fix           # Fix Prettier formatting
pnpm typecheck            # Run TypeScript type checking

# Testing
pnpm test                 # Run all tests
pnpm test:watch           # Run tests in watch mode
pnpm test:coverage        # Run tests with coverage (≥85% required)

# Database
pnpm prisma:generate      # Generate Prisma Client
pnpm prisma:migrate       # Run migrations
pnpm prisma:studio        # Open Prisma Studio
pnpm db:seed              # Seed database with test data

# Docker
pnpm docker:up            # Start all services
pnpm docker:down          # Stop all services

🏗️ Tech Stack

Frontend

• Next.js 14 - React framework with App Router
• TailwindCSS - Utility-first CSS
• Radix UI - Accessible component primitives
• Lucide React - Icon library
• GraphQL - API client (Relay planned)

Backend

• GraphQL Yoga - GraphQL server
• Prisma - Type-safe ORM
• PostgreSQL - Primary database
• Memcached - Caching layer
• MinIO - S3-compatible object storage
• MailHog - Email testing (dev)

DevOps

• Docker Compose - Local development services
• pnpm Workspaces - Monorepo management
• ESLint - Linting
• Prettier - Code formatting
• Vitest - Testing framework
• Husky - Git hooks

📚 Documentation

• Local Development Guide
• API Documentation
• Database Schema
• Deployment Guide
• Contributing Guidelines

🔐 Environment Variables

API (.env)

DATABASE_URL=postgresql://readoft:readoft_dev@localhost:5432/readoft_blog
PORT=4000
JWT_SECRET=your-secret-key
MEMCACHED_SERVERS=localhost:11211
S3_ENDPOINT=http://localhost:9000
SMTP_HOST=localhost
SMTP_PORT=1025

🧪 Testing

All tests must pass with ≥85% branch coverage before merging.

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test -w -k user-service

🎨 Design System

• Typography: Inter (UI), Source Serif Pro (content)
• Colors: CSS variables for light/dark themes
• Spacing: 4pt scale (4, 8, 12, 16...)
• Border Radius: 1rem default
• Mobile-first: Responsive breakpoints (sm: 640, md: 768, lg: 1024, xl: 1280)

📝 Commit Convention

We follow Conventional Commits:

feat(web): add post editor
fix(api): resolve authentication bug
chore(config): update eslint rules
docs: update README

🚢 Deployment

Prerequisites

• Node.js 20+ runtime
• PostgreSQL 16+
• S3-compatible storage
• SMTP server

Build

pnpm build

Production Environment

Set production environment variables and run:

pnpm --filter @app/web start
pnpm --filter @app/api start

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines.

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ by the readoft.blog team