Skip to content

Architecture Overview

Jump to bottom
Gary Norman edited this page Oct 7, 2025 · 2 revisions

Architecture Overview

Codex follows a clean architecture pattern with clear separation of concerns.

Project Structure

codex/
├── cmd/server/          # Application entry point
│   ├── main.go          # Server initialization, CLI
│   ├── migrations.go    # Database migrations
│   └── seed.go          # Database seeding
├── internal/
│   ├── app/             # App initialization & config
│   ├── db/              # Database connection
│   ├── dao/             # Generic data access layer
│   ├── sqlite/          # SQLite implementations
│   ├── models/          # Data models
│   ├── service/         # Business logic
│   ├── http/
│   │   ├── handlers/    # HTTP handlers
│   │   ├── middleware/  # Middleware (auth, logging)
│   │   └── routes/      # Router & DI registry
│   └── view/            # Template rendering
├── migrations/          # SQL schema files
├── assets/              # Static files (CSS, JS, icons)
└── scripts/             # Build & deployment scripts

Key Patterns

Dependency Injection

The application uses manual dependency injection via internal/http/routes/registry.go:

  1. Create flat handlers (Session, Reaction, Auth)
  2. Create handlers with single-level deps (Comment, Channel)
  3. Create complex handlers (User, Post, Home)
  4. Wire into RouteHandler struct

Generic DAO Pattern

All database operations use a generic DAO with type safety:

type DAO[T models.DBModel] struct {
    // Generic CRUD operations
}

Provides: All(), GetByID(), Insert(), Update(), Delete()

Database Models

All models implement the DBModel interface:

type DBModel interface {
    TableName() string
}

Struct fields use db tags for column mapping.

Template Rendering

  • Templates parsed once at startup
  • TempHelper provides access to App instance
  • Custom template functions for common operations
  • Composed from partials (.tmpl files)

Authentication Flow

  1. Session tokens stored in cookies
  2. auth middleware extracts user
  3. Context injection via WithUser middleware
  4. Handlers access user from r.Context()

Routing (Go 1.22+)

Uses enhanced servemux with method-based routing:

POST /register
GET /post/{postId}

Data Models

Core entities:

  • Users - User accounts and authentication
  • Posts - Forum posts
  • Comments - Threaded discussions
  • Reactions - Likes/dislikes
  • Channels - Topic organization
  • Memberships - User-channel relationships
  • Flags - Content moderation
  • Loyalty - User engagement tracking
  • Saved - Bookmarked posts
  • Mods - Channel moderators
  • Rules - Channel guidelines
  • Images - Media uploads
  • MutedChannels - Hidden channels

Technology Stack

  • Backend: Go 1.22+
  • Database: SQLite3 (github.com/mattn/go-sqlite3)
  • Routing: Standard library enhanced servemux
  • Templates: Go html/template
  • Frontend: Vanilla JavaScript, CSS, HTML
  • Build: Make
  • Containerization: Docker

Configuration

Environment variables loaded from .env:

DB_ENV=dev
DB_PATH=./identifier.sqlite

Performance Features

  • Database indexes for common queries
  • Template caching
  • Static file serving
  • Connection pooling
  • Graceful shutdown (10s timeout)

Development Tools

  • pprof server on localhost:6060
  • Colored console output (Catppuccin Mocha)
  • Interactive build menu
  • Automatic migrations

Clone this wiki locally