FrusaBlog - Full-Stack Personal Blog Platform

A modern, production-ready blog platform built with Next.js 15 (frontend) and FastAPI (backend), featuring passwordless authentication, admin dashboard, and comprehensive content management.

🚀 Features

🌐 Frontend (Next.js 15)

Modern Architecture: Built with Next.js 15 App Router, TypeScript, and Tailwind CSS v4
Responsive Design: Mobile-first design with beautiful, accessible layouts
Admin Dashboard: Complete content management system with rich text editor
Dark/Light Theme: System preference detection with manual toggle support
Search & Discovery: Full-text search with advanced tag filtering
File Management: Drag-and-drop file upload with image optimization
Real-time Updates: Optimistic UI updates with TanStack Query
Authentication: Passwordless email-based authentication flow

⚡ Backend (FastAPI)

High Performance: FastAPI with async/await and Python 3.13+
Type Safety: End-to-end type safety with Pydantic v2
Email Authentication: Secure passwordless authentication system
Permission System: Granular role-based access control
File Storage: Secure file upload with validation and streaming
Database Migrations: Alembic for schema versioning and management
Rich Logging: Structured logging with beautiful terminal output
API Documentation: Auto-generated OpenAPI/Swagger documentation

🛡️ Security & Performance

Passwordless Auth: No password storage or management required
Session Security: HTTP-only cookies with CSRF protection
Input Validation: Comprehensive data validation on frontend and backend
File Security: Type validation, size limits, and permission-based access
Performance: Optimized queries, caching, and code splitting

🏗️ Project Architecture

frusablog/
├── 📁 backend/                  # FastAPI Backend Application
│   ├── 📁 app/                  # Main application package
│   │   ├── 📁 api/              # API layer with versioning
│   │   │   └── 📁 routes/v1/    # API version 1
│   │   │       ├── controllers/ # FastAPI route handlers
│   │   │       ├── dto/         # Data Transfer Objects (Pydantic models)
│   │   │       └── providers/   # Business logic layer
│   │   ├── 📁 core/             # Core application components
│   │   │   ├── config/          # Configuration management
│   │   │   ├── db/              # Database models & setup
│   │   │   ├── security/        # Authentication & permissions
│   │   │   └── services/        # External services (email, storage)
│   │   └── 📁 utils/            # Utility functions and helpers
│   ├── 📁 migrations/           # Alembic database migrations
│   ├── 📁 fs/storage/           # Local file storage directory
│   ├── 📁 assets/templates/     # Email and other templates
│   ├── 📄 main.py               # Application entry point
│   ├── 📄 pyproject.toml        # Python dependencies & project config
│   ├── 📄 docker-compose.yml    # Development environment setup
│   └── 📄 Dockerfile            # Backend container configuration
│
└── 📁 frontend/                 # Next.js Frontend Application
    ├── 📁 src/                  # Source code directory
    │   ├── 📁 app/              # Next.js App Router
    │   │   ├── (main)/          # Public blog interface
    │   │   ├── (auth)/          # Authentication pages
    │   │   └── (admin)/         # Admin dashboard & management
    │   ├── 📁 components/       # Reusable React components
    │   │   ├── ui/              # shadcn/ui components
    │   │   ├── data/            # Data display components
    │   │   ├── layouts/         # Layout and navigation components
    │   │   └── wrappers/        # HOCs and context providers
    │   ├── 📁 lib/              # Libraries and configurations
    │   │   ├── api/             # API client and TypeScript types
    │   │   ├── config/          # Application configuration
    │   │   └── utils/           # Utility functions and helpers
    │   └── 📁 hooks/            # Custom React hooks
    ├── 📁 public/               # Static assets
    ├── 📄 package.json          # Node.js dependencies
    ├── 📄 next.config.ts        # Next.js configuration
    ├── 📄 tailwind.config.ts    # Tailwind CSS configuration
    └── 📄 Dockerfile            # Frontend container configuration

🏛️ Architecture Patterns

Backend (Layered Architecture)

Controllers → HTTP request/response handling
Providers → Business logic and orchestration
Models → Database entities and relationships
Services → External integrations (email, storage)

Frontend (Component Architecture)

Pages → App Router pages with layouts
Components → Reusable UI components
Hooks → Custom logic and state management
Libraries → API clients and utilities

🛠️ Technology Stack

🎨 Frontend

Framework: Next.js 15 with App Router
Language: TypeScript with strict mode
Styling: Tailwind CSS v4 with custom design system
UI Library: shadcn/ui with Radix UI primitives
State Management: TanStack Query (React Query v5)
Form Handling: React Hook Form with Zod validation
Rich Text: MDEditor with React Markdown
Icons: Lucide React icon library
Theme System: next-themes
Package Manager: pnpm or bun

⚙️ Backend

Framework: FastAPI with async/await
Language: Python 3.13+ with type hints
Database: PostgreSQL with SQLModel ORM
Migrations: Alembic for database versioning
Authentication: Custom email-based passwordless system
File Storage: Local filesystem (extensible to cloud storage)
Email Service: SMTP with Jinja2 templates
Validation: Pydantic v2 for data validation
Package Manager: UV for dependency management
Code Quality: Ruff for linting and formatting

🗄️ Database & Infrastructure

Database: PostgreSQL 17 with optimized indexing
Migration System: Alembic with automatic schema generation
Development: Docker Compose for local development
Deployment: Docker containers with multi-stage builds
Monitoring: Health checks and structured logging

🚀 Getting Started

📋 Prerequisites

Node.js 18+ and pnpm (or bun)
Python 3.13+ and UV package manager
PostgreSQL 17 (or Docker for development)
Git for version control

🐳 Quick Start with Docker (Recommended)

The fastest way to get the entire stack running:

# Clone the repository
git clone https://github.com/frusadev/frusablog.git
cd frusablog

# Start the backend services (API + Database)
cd backend
docker-compose up --build -d

# In a new terminal, start the frontend
cd ../frontend
pnpm install
pnpm dev

🌐 Access the application:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs

⚙️ Manual Development Setup

Backend Setup

Navigate to backend directory
```
cd backend
```
Install dependencies with UV
```
uv sync
```

Configure environment

cp .env.example .env
# Edit .env with your configuration (see Environment Variables section)

Set up PostgreSQL database

# Option 1: Use Docker for database only
docker run --name frusablog-db -e POSTGRES_PASSWORD=password -e POSTGRES_DB=frusablog -p 5432:5432 -d postgres:17

# Option 2: Use local PostgreSQL installation
createdb frusablog

Run database migrations
```
alembic upgrade head
```
Start the development server
```
python main.py
```
The API will be available at http://localhost:8000 📡

Frontend Setup

Navigate to frontend directory
```
cd frontend
```
Install dependencies
```
pnpm install
# or with bun
bun install
```

Configure environment

# Create .env.local with API connection settings
cat > .env.local << EOF
NEXT_PUBLIC_SERVER_URL=http://localhost:8000
NEXT_PUBLIC_API_VERSION=v1
EOF

Start development server
```
pnpm dev
# or with bun
bun dev
```
The application will be available at http://localhost:3000 🌐

� Documentation

📖 Core Documentation

API Documentation - Complete API reference with examples
Deployment Guide - Production deployment instructions
Frontend README - Frontend-specific documentation
Backend README - Backend setup and development
Backend Developer Guide - Technical implementation details

🔗 Quick Links

API Interactive Docs - Swagger UI (when running)
Redoc API Docs - Alternative API documentation
Database Schema - Data models and relationships

📊 API Overview

🔐 Authentication Endpoints

POST /v1/auth/email/register - User registration with email
POST /v1/auth/email/login - Login request (sends magic link email)
GET /v1/auth/email/authenticate/{session_id} - Complete authentication via email link
POST /v1/auth/logout - Logout and clear session

📝 Content Management

GET /v1/posts - Get published posts (with pagination)
GET /v1/posts/featured - Get featured posts
GET /v1/posts/drafts - Get draft posts (authenticated)
GET /v1/posts/search?q={query} - Search posts by title/content
GET /v1/post/{id} - Get specific post by ID
POST /v1/post - Create new post (authenticated)
PUT /v1/post/{id} - Update post (authenticated)
DELETE /v1/post/{id} - Delete post (authenticated)

💬 Comment System

GET /v1/comments/{post_id} - Get post comments with threading
POST /v1/comment - Create comment (authenticated)
PUT /v1/comment/{id} - Update comment (authenticated)
DELETE /v1/comment/{id} - Delete comment (authenticated)
POST /v1/comment/{id}/like - Like/unlike comment (authenticated)

📎 File Management

POST /v1/resource - Upload single file (authenticated)
POST /v1/resources - Upload multiple files (authenticated)
GET /v1/resource/{id} - Download/view file
DELETE /v1/resource/{id} - Delete file (authenticated)

👤 User Management

GET /v1/users/me - Get current user profile (authenticated)
GET /v1/users/me/can-post - Check posting permissions (authenticated)
PUT /v1/users/me - Update user profile (authenticated)

🗄️ Database Schema

👤 Core Models

User

interface User {
  id: string;              // Unique user identifier
  username: string;        // Unique username
  name: string;           // Display name
  email: string;          // Email address (private)
  created_at: datetime;   // Account creation timestamp
  roles: Role[];          // Assigned roles for permissions
}

Post

interface Post {
  id: UUID;               // Unique post identifier
  title: string;          // Post title (max 100 chars)
  description: string;    // Post description (max 400 chars)
  content: string;        // Markdown content
  cover?: UUID;           // Cover image file resource ID
  likes: number;          // Like count
  published: boolean;     // Publication status
  archived: boolean;      // Archive status
  featured: boolean;      // Featured status for homepage
  created_at: datetime;   // Creation timestamp
  author: User;           // Post author
  tags: Tag[];           // Associated tags
  comments: Comment[];    // Post comments
}

Comment

interface Comment {
  id: UUID;               // Unique comment identifier
  content: string;        // Comment text
  likes: number;          // Like count
  level: number;          // Nesting level (0=top, 1=reply)
  created_at: datetime;   // Creation timestamp
  author: User;           // Comment author
  post: Post;             // Parent post
  parent?: Comment;       // Parent comment (for replies)
  children: Comment[];    // Child comments
}

Tag

interface Tag {
  id: UUID;               // Unique tag identifier
  name: string;           // Tag name (unique)
  posts: Post[];          // Posts with this tag
}

🔐 Security Models

Role & Permission System

interface Role {
  id: UUID;
  name: string;           // Role name (e.g., "admin", "user")
  description: string;
  users: User[];          // Users with this role
  permissions: Permission[];
}

interface Permission {
  id: UUID;
  role: Role;             // Associated role
  resource_name: string;  // Resource type (e.g., "post", "file")
  resource_id?: string;   // Specific resource ID (optional)
  action_name: string;    // Action type (e.g., "read", "write", "admin")
}

Authentication Sessions

interface AuthSession {
  id: string;             // Session identifier for email links
  user: User;            // Associated user
  expires_at: datetime;   // Expiration time (1 hour)
  expired: boolean;       // Manual expiration flag
}

interface LoginSession {
  id: string;             // Session identifier for cookies
  user: User;            // Associated user
  expires_at: datetime;   // Expiration time (30 days)
  created_at: datetime;   // Creation timestamp
}

📎 File Management

interface FileResource {
  id: UUID;               // Unique file identifier
  name: string;           // Original filename
  filetype: string;       // MIME type
  protected: boolean;     // Permission-based access
  created_at: datetime;   // Upload timestamp
  owner: User;            // File owner
}

🎨 Frontend Architecture

📱 App Router Structure

(main) - Public blog interface
- / - Homepage with featured and recent posts
- /posts - All posts with pagination and filtering
- /post/[slug] - Individual post view with comments
- /search - Search interface with filters
(auth) - Authentication flow
- /login - Email-based login request
- /register - User registration
- /authenticate/[session_id] - Magic link authentication
(admin) - Admin dashboard (authenticated)
- /admin - Posts management dashboard
- /admin/posts/new - Create new post
- /admin/posts/[id]/edit - Edit existing post
- /admin/files - File management interface

🧩 Component Architecture

components/
├── ui/              // shadcn/ui components (Button, Input, etc.)
├── data/            // Data display components
│   ├── PostCard     // Post preview component
│   ├── CommentThread // Comment system
│   └── TagList      // Tag display
├── layouts/         // Layout components
│   ├── Navigation   // Site navigation
│   ├── Footer       // Site footer
│   └── Sidebar      // Content sidebar
└── wrappers/        // HOCs and providers
    ├── AuthGuard    // Authentication protection
    ├── ThemeProvider // Theme management
    └── QueryProvider // TanStack Query setup

🔄 State Management Strategy

Server State: TanStack Query for API data caching
Global State: React Context for user and theme state
Form State: React Hook Form with Zod validation
Local State: useState for component-specific UI state

🔒 Security Features

🛡️ Authentication & Authorization

Passwordless Authentication: Secure email-based magic link system
Session Management: HTTP-only cookies with CSRF protection
Role-Based Access Control: Granular permission system for resources
Permission Inheritance: Admin role bypasses specific permission checks
Session Expiration: Automatic cleanup of expired auth sessions

📁 File Security

Upload Validation: MIME type detection and file size restrictions
Protected Resources: Permission-based file access control
Secure Storage: UUID-based file naming to prevent enumeration
Content-Type Validation: Server-side file type verification
Access Logging: Comprehensive file access tracking

🔍 Data Validation & Protection

Frontend Validation: Zod schema validation with TypeScript
Backend Validation: Pydantic model validation with Python
SQL Injection Prevention: Parameterized queries with SQLModel
XSS Protection: HTML sanitization and CSP headers
Input Sanitization: Comprehensive input cleaning and validation
Type Safety: End-to-end type safety across the stack

🎯 Key Features Deep Dive

📊 Admin Dashboard

Content Management: Create, edit, delete, and organize blog posts
Draft System: Save and manage unpublished content with auto-save
Featured Posts: Highlight important content on homepage
Tag Management: Create and organize content categories
File Upload: Drag-and-drop file management with image preview
Analytics: View post performance and engagement metrics
Search & Filter: Advanced content discovery and organization tools

✍️ Rich Text Editor

Markdown Support: Full GitHub-flavored markdown syntax
Live Preview: Real-time split-pane preview mode
Syntax Highlighting: Code block highlighting with multiple languages
Image Embedding: Direct image uploads with automatic optimization
Table Support: Rich table editing and formatting
Link Management: Easy link insertion and validation
Auto-Save: Automatic draft saving to prevent data loss

💬 Comment System

Nested Threading: Two-level comment threading for discussions
Like System: User engagement tracking with optimistic updates
Real-time Updates: Live comment updates without page refresh
Moderation Tools: Admin comment management and spam protection
User Mentions: @mention system for user notifications
Comment Editing: Edit and delete capabilities with version history

📧 Email System

Beautiful Templates: Responsive HTML email templates with Jinja2
Authentication Emails: Secure magic link emails for login/registration
Welcome Series: Automated welcome email sequence for new users
Notification System: Comment and mention notifications
Template Management: Easy email template customization
Delivery Tracking: Email delivery status and analytics

� Development Workflow

🧪 Code Quality & Testing

# Frontend quality checks
cd frontend
pnpm lint          # ESLint with TypeScript rules
pnpm format        # Prettier code formatting
pnpm type-check    # TypeScript strict mode checking
pnpm test          # Jest with React Testing Library
pnpm test:e2e      # Playwright end-to-end tests

# Backend quality checks
cd backend
ruff check         # Fast Python linting
ruff format        # Code formatting
pytest             # Comprehensive test suite
pytest --cov=app  # Coverage reporting
mypy app/          # Type checking

🚀 Deployment Options

Production Deployment

Frontend: Optimized for Vercel, Netlify, or Docker deployment
Backend: Docker containerization with multi-stage builds
Database: PostgreSQL with connection pooling and migrations
CDN: Static asset optimization and caching

Development Deployment

Docker Compose: Complete local development stack
Hot Reload: Live reload for both frontend and backend
Database Seeding: Sample data for development and testing

⚡ Performance Optimizations

� Frontend Performance

Next.js App Router: Latest routing with automatic code splitting
Image Optimization: Next.js Image component with lazy loading
Bundle Optimization: Tree shaking and dead code elimination
Caching Strategy: TanStack Query with intelligent cache invalidation
Lazy Loading: Component-level lazy loading for better LCP
Static Generation: ISR (Incremental Static Regeneration) for posts
Web Vitals: Optimized Core Web Vitals scores

⚙️ Backend Performance

Async Architecture: Full async/await implementation with uvloop
Database Optimization: Efficient SQLModel queries with eager loading
Connection Pooling: PostgreSQL connection pool management
Response Streaming: Efficient file serving with range requests
Query Optimization: Strategic database indexing and query planning
Background Tasks: Non-blocking email and file processing
Health Monitoring: Performance metrics and monitoring endpoints

�🌍 Environment Configuration

🔧 Backend Environment Variables

# Database
DB_STRING=postgresql+psycopg2://user:pass@localhost:5432/frusablog
ALEMBIC_DB_URL=postgresql+psycopg2://user:pass@localhost:5432/frusablog

# Application
DEBUG=True
PORT=8000
STORAGE=fs/storage

# Email (for authentication)
EMAIL_APP_PASSWORD=your-app-password
APP_EMAIL_ADDRESS=your-email@domain.com
EMAIL_TEMPLATES_PATH=assets/templates/email/

# URLs
FRONTEND_URL=http://localhost:3000
BACKEND_URL=http://localhost:8000

🎨 Frontend Environment Variables

# API Configuration
NEXT_PUBLIC_SERVER_URL=http://localhost:8000
NEXT_PUBLIC_API_VERSION=v1
NEXT_PUBLIC_API_URL=http://localhost:8000/v1

# Optional: Analytics and monitoring
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Contribution Guide

🍴 Fork the repository

# Click "Fork" on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/frusablog.git
cd frusablog

🌿 Create a feature branch

git checkout -b feature/amazing-feature
# or for bug fixes
git checkout -b bugfix/issue-description

💻 Make your changes
- Follow the existing code style and patterns
- Add tests for new functionality
- Update documentation as needed

🧪 Run quality checks

# Backend checks
cd backend
ruff check && ruff format
pytest

# Frontend checks
cd ../frontend
pnpm lint && pnpm type-check
pnpm test

📝 Commit with conventional commits

git commit -m "feat: add amazing new feature"
# or
git commit -m "fix: resolve login issue"
# or
git commit -m "docs: update API documentation"

🚀 Push and create PR

git push origin feature/amazing-feature
# Then create a Pull Request on GitHub

📋 Contribution Guidelines

Code Style: Follow existing patterns and use the configured linters
Testing: Add tests for new features and ensure existing tests pass
Documentation: Update relevant documentation for API or feature changes
Commit Messages: Use conventional commits (feat, fix, docs, etc.)
Pull Requests: Provide clear description of changes and link any issues

🐛 Bug Reports & Feature Requests

Bug Reports: Use the GitHub issue template with reproduction steps
Feature Requests: Describe the feature and its use case clearly
Security Issues: Report privately via email first

� Troubleshooting

🔧 Common Issues & Solutions

Backend Issues

# Database connection issues
❌ Error: "could not connect to server"
✅ Solution: Ensure PostgreSQL is running and credentials are correct
   docker ps  # Check if database container is running
   docker-compose logs db  # Check database logs

# Migration errors
❌ Error: "Target database is not up to date"
✅ Solution: Run migrations
   alembic upgrade head

# Email configuration issues
❌ Error: "Authentication failed" for SMTP
✅ Solution: Check email app password and SMTP settings
   # For Gmail, use App Password, not regular password

Docker Issues

# Port conflicts
❌ Error: "Port already in use"
✅ Solution: Stop conflicting services or change ports
   docker-compose down
   lsof -i :8000  # Check what's using the port

# Volume permission issues
❌ Error: "Permission denied" for file uploads
✅ Solution: Fix volume permissions
   docker-compose down
   sudo chown -R $USER:$USER backend/fs
   docker-compose up

📞 Getting Help

📖 Documentation: Check the API.md and component READMEs
🐛 Issues: Search existing issues or create a new one
💬 Discussions: Use GitHub Discussions for questions
📧 Email: Contact @frusadev for urgent issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Useful Links & Resources

📚 Documentation & Tutorials

Next.js 15 Documentation - Next.js framework documentation
FastAPI Documentation - FastAPI framework guide
shadcn/ui Components - UI component library
TanStack Query - Data fetching and caching
SQLModel Documentation - Database ORM
Tailwind CSS - CSS framework

�️ Development Tools

UV Documentation - Python package manager
Ruff Documentation - Python linter
Alembic Documentation - Database migrations
pnpm Documentation - Node.js package manager

🚀 Deployment & Hosting

Vercel - Frontend deployment platform
Railway - Full-stack deployment
Docker Hub - Container registry
PostgreSQL Cloud - Database hosting

�📧 Contact & Support

👨‍💻 Developer: Daniel Ametsowou
🐙 GitHub: @frusadev
🔗 Project: https://github.com/frusadev/frusablog

🤝 Community

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Direct Contact: Open an issue for feature requests or questions

Built with ❤️ using modern web technologies

FrusaBlog - Where ideas come to life ✨

Name		Name	Last commit message	Last commit date
Latest commit History 256 Commits
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
API.md		API.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
docker-compose.yml		docker-compose.yml

Frusadev/frusablog

Folders and files

Latest commit

History

Repository files navigation

FrusaBlog - Full-Stack Personal Blog Platform

🚀 Features

🌐 Frontend (Next.js 15)

⚡ Backend (FastAPI)

🛡️ Security & Performance

🏗️ Project Architecture

🏛️ Architecture Patterns

Backend (Layered Architecture)

Frontend (Component Architecture)

🛠️ Technology Stack

🎨 Frontend

⚙️ Backend

🗄️ Database & Infrastructure

🚀 Getting Started

📋 Prerequisites

🐳 Quick Start with Docker (Recommended)

⚙️ Manual Development Setup

Backend Setup

Frontend Setup

� Documentation

📖 Core Documentation

🔗 Quick Links

📊 API Overview

🔐 Authentication Endpoints

📝 Content Management

💬 Comment System

📎 File Management

👤 User Management

🗄️ Database Schema

👤 Core Models

User

Post

Comment

Tag

🔐 Security Models

Role & Permission System

Authentication Sessions

📎 File Management

🎨 Frontend Architecture

📱 App Router Structure

🧩 Component Architecture

🔄 State Management Strategy

🔒 Security Features

🛡️ Authentication & Authorization

📁 File Security

🔍 Data Validation & Protection

🎯 Key Features Deep Dive

📊 Admin Dashboard

✍️ Rich Text Editor

💬 Comment System

📧 Email System

� Development Workflow

🧪 Code Quality & Testing

🚀 Deployment Options

Production Deployment

Development Deployment

⚡ Performance Optimizations

� Frontend Performance

⚙️ Backend Performance

�🌍 Environment Configuration

🔧 Backend Environment Variables

🎨 Frontend Environment Variables

🤝 Contributing

🚀 Quick Contribution Guide

📋 Contribution Guidelines

🐛 Bug Reports & Feature Requests

� Troubleshooting

🔧 Common Issues & Solutions

Backend Issues

Docker Issues

📞 Getting Help

📄 License

🔗 Useful Links & Resources

📚 Documentation & Tutorials

�️ Development Tools

Packages