Owlistic

Owlistic is a privacy-first, self-hosted productivity app that combines WYSIWYG note editing, inline task management, and real-time synchronization in a single deployable stack. Built for individuals and teams who want full data ownership without sacrificing the polish of commercial tools like Evernote, it runs entirely on your infrastructure via Docker Compose.

The backend is written in Go using the Gin framework, with PostgreSQL for persistence and NATS JetStream for event-driven messaging between services. The frontend is a Flutter application targeting web and mobile, using the super_editor package for rich document editing and WebSocket streaming for live updates. A dedicated BlockNodeMapping layer maintains bidirectional references between editor document nodes and backend database blocks, enabling accurate real-time edit reconciliation without polling.

Owlistic is actively developed with comprehensive test coverage across its route, service, broker, model, and database layers. It ships as a multi-container Docker stack—backend API, Flutter web frontend, PostgreSQL, and NATS—making deployment straightforward for any host with Docker installed. All data stays on your servers, and the GPLv3 license ensures the codebase remains open.

What You Get

• Rich WYSIWYG Editor - A full-featured visual editor powered by the super_editor package, supporting inline formatting, headings, lists, and floating toolbars without requiring users to write Markdown syntax.
• Real-time Sync - Notes, tasks, and blocks update instantly across all connected clients via WebSocket event streaming, so edits made on one device appear on another without manual refresh.
• Notebooks/Notes Tree - Hierarchical organization of notes into nested notebooks, giving users a structured knowledge hierarchy similar to Evernote’s folder model.
• Inline Todo Items - Create and manage checklists directly inside notes using the /task inline command; checkboxes persist across sessions and sync to the tasks view in real time.
• JWT-Based Auth and Role-Based Access Control - Secure user authentication with configurable role permissions (admin, editor, viewer) for collaborative workspaces and controlled access delegation.
• Trash and Soft Deletion - Deleted notes and tasks move to a recoverable trash bin, preventing accidental permanent data loss and enabling restore workflows.
• Dark and Light Mode - System-aware theme switching with manual override, using a cohesive design system backed by Ionicons and Material components.
• Markdown Import - Import existing .md files to migrate content from Joplin, Obsidian, or any Markdown-based workflow without retyping.

Common Use Cases

• Personal knowledge base management - A researcher deploys Owlistic on a home server to collect and link notes from multiple projects, with inline tasks tracking action items, all synced to a phone and laptop without any external cloud dependency.
• Small team documentation hub - A startup team self-hosts Owlistic to collaboratively author internal runbooks and meeting notes with real-time co-editing and role-based permissions that prevent junior members from accidentally deleting shared content.
• Student project and course organization - A university student organizes lecture notes, reading summaries, and assignment checklists in nested notebooks, importing annotated Markdown exports from other tools and tracking todos inline.
• Evernote or Joplin migration - A long-time Evernote subscriber wanting to escape recurring fees migrates their note archive to Owlistic via Markdown import, gaining real-time sync and self-hosting control with a comparable editing experience.
• Privacy-sensitive note-taking - A journalist or legal professional stores sensitive case notes on an air-gapped or privately networked Owlistic instance, eliminating exposure to third-party cloud storage entirely.

Under The Hood

Architecture Owlistic follows a clean layered architecture with a Go backend and Flutter frontend separated by a well-defined REST and WebSocket API. The backend organizes code into discrete layers—models, services, routes, middleware, database, and broker—each with explicit interfaces that enable dependency injection and simplified unit testing. An event-driven core decouples data mutations from downstream effects: when a note or block changes, a domain event is written to PostgreSQL and then dispatched to NATS JetStream, where separate consumers handle real-time notification fan-out and block-task synchronization. This outbox-style pattern ensures events survive crashes and are delivered reliably. On the frontend, Flutter’s Provider pattern with a ServiceLocator gives ViewModels access to services without tight coupling, and a broadcast stream architecture propagates authentication state and WebSocket events across the UI layer.

Tech Stack The backend runs Go 1.23 with the Gin web framework handling HTTP routing, JWT middleware for authentication, and gorilla/websocket for persistent client connections. Data persistence uses PostgreSQL accessed via GORM with migration support, while NATS with JetStream replaces an earlier Kafka-style broker for reliable, ordered event streaming. The Flutter frontend targets web and mobile using go_router for declarative routing, the super_editor package for block-based document editing, and web_socket_channel for real-time communication. The entire stack deploys via Docker Compose with distinct network segments for the API, database, and event bus, enabling isolation without Kubernetes overhead.

Code Quality Owlistic maintains comprehensive test coverage across all backend layers—models, routes, services, broker, and database each have dedicated test files using testify assertions and go-sqlmock for database simulation without live connections. Services are defined as interfaces, making it straightforward to substitute mock implementations in tests. Error handling is explicit throughout, using named error types from a central errors file and structured HTTP responses rather than swallowing errors. The Flutter frontend uses flutter_lints and the analysis_options.yaml enforces static analysis. Overall, the codebase reflects disciplined engineering practices for a project that is still in its early public releases.

What Makes It Unique Owlistic’s most technically distinctive contribution is its BlockNodeMapping system—a bidirectional, conflict-aware mapping layer between super_editor’s DocumentNodes and backend database Blocks. Rather than reconciling entire documents on save, it tracks per-block user modification timestamps alongside server timestamps, applying server updates only when the server version is strictly newer than the last local edit. This merge strategy avoids overwriting in-flight edits during real-time sync without requiring operational transforms or CRDTs. Combined with the outbox event pattern on the backend, the result is a self-hosted note editor with conflict-avoidance semantics that rivals the consistency guarantees of hosted collaborative tools.

Self-Hosting

Owlistic is licensed under the GNU General Public License v3.0, which is a strong copyleft license. In practical terms this means you can run, modify, and distribute Owlistic freely, including for commercial internal use, but if you distribute a modified version of the software externally you must release that modified source under the same GPLv3 terms. For teams deploying Owlistic purely for internal use—the common self-hosting scenario—the copyleft provisions typically do not create any redistribution obligations.

Running Owlistic yourself means operating a four-service Docker Compose stack: a Go API server, a Flutter web frontend, a PostgreSQL database, and a NATS JetStream broker. You are responsible for provisioning infrastructure (a single modest VPS is sufficient for small teams), configuring environment variables for database credentials and JWT secrets, managing PostgreSQL backups, monitoring service health, and applying upstream updates manually. The project provides Dockerfiles and a compose file with sensible defaults, which lowers the initial setup bar, but operational continuity is entirely your responsibility. There is no built-in backup automation, high-availability configuration, or managed upgrade tooling.

There is currently no commercial cloud or SaaS tier for Owlistic—it is purely community-developed and self-hosted. This means you gain full data sovereignty and no subscription costs, but you also forgo the support contracts, SLA guarantees, automatic failover, managed backups, and professional security patching that a hosted service would provide. For small teams comfortable managing a Docker-based stack, the trade-off is favorable. For organizations with strict uptime requirements or limited DevOps capacity, the operational overhead should be weighed carefully before committing to Owlistic as a primary documentation or knowledge management tool.