Augustus

A modular desktop application for managing media collections, built with custom-engineered frameworks

---

Overview

Augustus is a Kotlin Multiplatform desktop application for tracking manga, light novels, and game collections. What makes it unique is that it's built entirely on custom-engineered frameworks — a form engine, report engine, and database access layer — designed from scratch to solve real problems without the overhead of traditional solutions.

Highlights

Component	Description
Octavius for PostgreSQL	External Library. A wire-protocol driver, a data access client over it, and a migrator — SQL-first, with type mapping read from the catalog
Form Engine	Declarative form builder: dependencies, cross-control actions, repeatable sections, three-level validation
Report Engine	Turns a SQL query into an interactive table — filters that write SQL, multi-column sorting, column management, saved layouts
Browser Extension	Kotlin/JS Chrome extension for importing data from external sources

Tech Stack

Core Kotlin Multiplatform Compose Multiplatform PostgreSQL 18+ Material 3

Backend / Data Octavius for PostgreSQL (custom wire-protocol driver + client) HikariCP Ktor (API server) kotlinx-serialization

Architecture

The project follows a modular distributed architecture. The Core Database layer is developed as a separate library.

Augustus/
├── desktop-app/             # Main application entry point
│
├── form-engine/             # Declarative form framework
├── report-engine/           # Dynamic table framework
├── ui-core/                 # Shared UI components, theme, utilities
├── navigation/              # Tab/screen stack router — app side, engines do not depend on it
│
├── feature-asian-media/     # Manga, novels, manhwa tracking
├── feature-books/           # Books and literature tracking
├── feature-games/           # Game collection management
├── feature-sandbox/         # Sandbox testing environment
├── feature-contract/        # Shared feature interfaces and models
│
├── api-server/              # REST API for browser extension
├── api-contract/            # Shared API models between server and extension
└── browser-extension/       # Kotlin/JS Chrome extension

Note: The database module is externalized.

Custom Frameworks

Form Engine

Turns a schema — controls plus a display order — into a full CRUD form:

• Rich control types: primitives, dropdowns (enum/database), dates/intervals, files, sections, repeatable rows
• Dependencies: show/hide or require a control based on another control's value
• Cross-control actions: a control action can read or write any other control by relative or wildcard path
• Three-level validation: per-field, business rules, and per-action, each with its own error surface
• Diffed repeatable rows: added/modified/deleted rows separated for you, not just a flat list

Learn more →

Report Engine

Turns a SQL query into an interactive table — the base query is never rewritten, just wrapped in a subquery:

• Filters that write SQL: each column type builds its own parameterised query fragment, with explicit NULL semantics
• Multi-column sorting: ordered, drag-reorderable sort chips
• Column management: visibility and order, adjusted at runtime
• Saved layouts: filters, sorting, visibility and page size persisted per report in the database
• Server-side pagination: COUNT + LIMIT/OFFSET, never loads the full result set

Learn more →

Database Layer (Octavius for PostgreSQL)

SQL-first approach with automatic mapping (imported as a library):

// Your query shapes the result — not the ORM
val books = db.select("id", "title", "author", "status")
    .from("books")
    .where("status = @status")
    .orderBy("title")
    .fetchObjects<Book>("status" to BookStatus.Reading)

The schema is kept up to date by the same library's migrator — OctaviusMigrator(dataSource).migrate() at startup, over the V<version>__<description>.sql files each module ships in its own resources.

See Repository →

Getting Started

Requirements

• JDK 25+
• PostgreSQL 18+ — the driver speaks Wire Protocol v3.2, which no earlier server does
• Database augustus created locally

Run

./gradlew run

Build Browser Extension

./gradlew assembleBrowserExtension
# Output: browser-extension/build/extension/

Localization

Translations are managed using the octavius-i18n Gradle plugin. Check its repository for detailed instructions on adding and configuring translations.