forum

README

A forum for finding all the help you need with code.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Architecture
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Codex is a feature-rich web forum application built with Go that provides a modern, community-driven platform for discussions and knowledge sharing. Designed with developers in mind, Codex offers a comprehensive set of features for creating, organizing, and moderating online communities.

Key Features

User Management

• Authentication & Authorization - Secure user registration and login with session-based authentication
• User Profiles - Customizable profiles with avatars and user information
• Role-Based Access - Moderator and admin roles with granular permissions

Content & Communication

• Posts & Comments - Create threaded discussions with rich content
• Channels - Organize discussions into topic-based channels
• Channel Membership - Join/leave channels to customize your feed
• Reactions - Like and dislike posts and comments to surface quality content
• Bookmarks - Save posts for later reference

Community Features

• Channel Rules - Set community guidelines per channel
• Mute Channels - Hide channels you're not interested in
• Content Filtering - Filter posts by channel, reactions, and user-created content

Media & Design

• Image Uploads - Attach images to posts, channels, and user profiles
• Concurrent Image Processing - Worker pool for background image processing
• Responsive Design - 🚧 Work in progress for mobile optimization
• Modular CSS Architecture - Organized stylesheets for maintainability

Engagement & Rewards

• Loyalty System - Track user engagement and participation
• Search Functionality - Find posts, channels, and users quickly

Built With

• Backend: Go 1.22+
• Database: SQLite3
• Templating: Go HTML templates
• Containerization: Docker
• Build System: Make

Architecture

UUID System

Codex uses a robust UUID implementation for user identification throughout the application:

• UUIDField Type - Custom type wrapping github.com/google/uuid with database driver interfaces
• Automatic Conversion - Implements driver.Valuer and sql.Scanner for seamless SQLite integration
• BLOB Storage - UUIDs stored as 16-byte BLOBs in SQLite for efficiency
• JSON Marshaling - Automatic string conversion for API responses
• Type Safety - Compile-time guarantees for user ID operations

Key Files:

• internal/models/uuidfield-models.go - UUIDField type definition
• internal/dbutils/uuid.go - Database utilities

Concurrent Image Processing

Production-ready worker pool for background image processing:

• Worker Pool Pattern - Configurable number of goroutines with buffered job queue
• Graceful Shutdown - Context-based timeout with proper cleanup
• Atomic State Management - Race-free shutdown tracking using sync/atomic
• Database Integration - Stores image metadata after successful processing
• Error Handling - Comprehensive validation and colored logging

Key Files:

• internal/workers/image_worker.go - Worker pool implementation
• internal/workers/image_worker_test.go - Unit tests (9 tests)
• internal/workers/image_worker_integration_test.go - Integration tests
• internal/workers/image_worker_database_test.go - Database integration tests

Features:

• Non-blocking job submission with queue-full detection
• Image validation (JPEG, PNG, GIF)
• Directory-based organization (post-images, user-images, channel-images)
• Metadata persistence to database with path tracking

Database Patterns

Generic DAO Layer (🚧 Planned):

• Type-safe CRUD operations using Go generics: DAO[T models.DBModel]
• Automatic struct-to-SQL mapping via reflection
• Currently using model-specific implementations in internal/sqlite/

Migration System:

• Sequential SQL migrations in migrations/ directory
• Automatic tracking of applied migrations
• Run with: bin/codex migrate

Database Seeding:

• Populate initial data for development
• Run with: bin/codex seed

Recent Migrations:

• 005_add_image_path.sql - Adds Path column to Images table for worker pool integration

CSS Architecture

Modular System: Codex uses a modular CSS architecture for maintainability and performance:

• Import-Based Structure - main.css imports 27+ specialized modules
• Logical Organization - Separated by concern (typography, layout, buttons, forms, etc.)
• OKLCH Color System - Modern color space with Catppuccin Mocha palette
• CSS Variables - Centralized theming in variables.css

Key Modules:

• colors-oklch.css - OKLCH color definitions with light/dark mode support
• variables.css - CSS custom properties for spacing, shadows, z-index
• layout.css, typography.css, buttons.css, forms.css - Core UI modules
• popovers.css, feeds.css, cards.css - Feature-specific styles

Benefits:

• Easy navigation and maintenance
• Reduced merge conflicts
• Better caching (specific module updates)
• Clear separation of concerns

Concurrency & Fault Tolerance

Context Propagation:

• Request-scoped context throughout entire database layer
• All database operations accept context.Context as first parameter
• Automatic query cancellation when clients disconnect
• Timeout enforcement via context deadlines
• Foundation for distributed tracing and request correlation
• Template functions use context.Background() for synchronous rendering

Implementation:

• 17 models updated (~100 methods) with context parameters
• All handlers extract r.Context() and pass to model calls
• Transactions use BeginTx(ctx, nil) for context-aware operations
• Worker pools respect context for graceful shutdown

Request Tracing:

• UUID-based request IDs for distributed tracing
• Context propagation across middleware and handlers
• X-Request-ID response headers for client-side debugging
• Automatic correlation of logs across concurrent operations

Circuit Breaker Pattern:

• Database protection with automatic failure detection
• Configurable failure threshold (5 failures, 5s timeout)
• Half-open state for recovery testing
• Shared circuit state across concurrent goroutines
• Located in internal/patterns/circuitbreaker.go

Async Logging System:

• Worker pool for non-blocking log writes
• Buffered queue (1000 entries) for high throughput
• Graceful shutdown with queue draining
• Database persistence for request logs

Graceful Shutdown:

• Ordered shutdown sequence (HTTP → Logger → Database)
• Context-based timeout for cleanup operations
• Wait for in-flight requests before closing connections

Colorized Logging:

• Context-aware logging with request ID injection
• Color-coded output (🟢 info, 🟠 warn, 🔴 error)
• Emoji icons for visual scanning
• Automatic timestamp and formatting

Key Files:

• internal/sqlite/*.go - Context-aware database models
• internal/http/handlers/*.go - Context extraction and propagation
• internal/view/render.go - Template function wrappers
• internal/http/middleware/tracing.go - Request ID middleware
• internal/patterns/circuitbreaker.go - Circuit breaker implementation
• internal/workers/logger_pool.go - Async logging worker pool
• internal/models/logs-models.go - Colorized logging functions
• cmd/server/main.go - Graceful shutdown implementation

(back to top)

(back to top)

Getting Started

Prerequisites

• Go 1.22 or higher
• SQLite3
• WSL users only: dos2unix package (for fixing line endings)

  sudo apt install dos2unix
  

Installation

1. Clone the repo

   git clone https://github.com/gary-norman/forum.git
   cd forum
   

2. Set up environment configuration

   cp .env.example .env
   # Edit .env and configure DB_PATH for your environment
   # - Local development: ./identifier.sqlite
   # - WSL: ./identifier.sqlite or /tmp/codex_dev.db
   # - Production with FUSE: /var/lib/db-codex/database.db (ext4)
   

Note for FUSE filesystems: If your application code is on a FUSE filesystem (network mount, cloud storage), place the database on a native filesystem like ext4 at /var/lib/. FUSE filesystems don't properly support SQLite's file locking mechanisms.

WSL-Specific Setup

If you're using Windows Subsystem for Linux (WSL), you may encounter line ending issues. Fix them with:

# Option 1: Use the Make target (recommended)
make fix-line-endings

# Option 2: Manual fix with dos2unix
dos2unix Makefile scripts/*.sh

# Option 3: Manual fix with sed (if dos2unix not available)
sed -i 's/\r$//' Makefile scripts/*.sh

Then run the configuration:

make configure  # Will auto-detect WSL and use appropriate paths

Why this is needed: Git may check out files with Windows (CRLF) line endings on WSL, which breaks shell scripts and Makefiles. The .gitattributes file prevents this for new clones, but existing repositories may need manual fixing.

Usage

Option 1: Using Make (Recommended)

The project includes an interactive menu system for easy command execution:

make menu

This will display an interactive menu with the following options:

• build - Build the web server application
• run - Run the web server application
• build-run - Build and run the application in sequence
• Docker - Docker management submenu (configure, build image, run container)
• Scripts - Script management submenu (install, verify, backup scripts)

You can navigate using arrow keys or type the option number.

Option 2: Using Make Directly

# Build the application
make build

# Run the application
make run

# Build and run
make build-run

# Docker commands
make configure        # Configure Docker options
make build-image      # Build Docker image
make run-container    # Run Docker container

# Script management
make install-scripts  # Install/update scripts
make verify-scripts   # Verify script checksums
make backup-scripts   # Backup scripts

Option 3: Direct Terminal Commands

If you prefer not to use Make:

# Build the application
go build -o bin/codex github.com/gary-norman/forum/cmd/server

# Run the application
./bin/codex

# Build and run
go build -o bin/codex github.com/gary-norman/forum/cmd/server && ./bin/codex

The server will start on http://localhost:8888 by default.

Database Management

# Run database migrations
bin/codex migrate

# Seed the database with initial data
bin/codex seed

Note: The application will automatically run migrations on first startup, but you can run them manually using the commands above.

(back to top)

For more examples, please refer to the Documentation

(back to top)

Roadmap

Completed ✓

• Core forum functionality (posts, comments, reactions)
• User authentication and authorization
• Channel-based organization
• Image upload support
• Concurrent image processing with worker pool
• UUID-based user identification system
• Modular CSS architecture
• Database migration system
• Request tracing with context propagation
• Context-aware database layer (17 models, ~100 methods)
• Circuit breaker pattern for fault tolerance
• Async logging with worker pool
• Graceful shutdown with cleanup
• Colorized logging system
• Search functionality
• Docker deployment
• Interactive build menu

In Progress 🚧

• Responsive design (mobile optimization)
• Error handling improvements (400/500 pages)
• Enhanced UI/UX refinements
• Image optimization (resizing, thumbnails)
• Logging migration (5/10 handlers complete - see LOGGING_MIGRATION.md)

Planned 📋

Architecture Improvements

• Generic DAO layer with Go generics
• Type-safe database queries with reflection
• Complete logging migration for all handlers

Advanced Features

• Bookmark system
• Real-time notifications
• Advanced filtering options
• User reputation system
• Markdown support for posts

Security Enhancements

• Rate limiting
• Enhanced session management
• Two-factor authentication
• Content sanitization improvements

Moderation Tools

• Content flags and reporting system
• Channel moderation roles
• Admin dashboard
• Automated content filtering
• User reporting system
• Moderator activity logs

Authentication

• OAuth integration (GitHub, Google)
• Email verification
• Password recovery

See the open issues for a full list of proposed features (and known issues).

View progress by milestone.

(back to top)

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Made with contrib.rocks.

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Gary Norman - @gary - email@gary.com

Kamil Ornal - @kamil - email@kamil.com

(back to top)

(back to top)