Dictos

Local-first, keyboard-driven, and cross-platform personal dictionaries, for extremely low friction.

Dictos is an open-source app for building and managing personal dictionaries while reading, learning, and collecting language material. It stores your data locally first, keeps the interface fast, and is designed to sync across devices without making the network the source of truth.

The project is still early. The Terminal UI is the main usable client today, with a Web client and central server under development.

Quick Start

The supported development workflow assumes a devenv shell environment.

git clone git@github.com:Roverp1/dictos.git
cd dictos
devenv shell

secretspec config init
secretspec check

bun install
devenv up
bun run dev:tui

This starts fully local Terminal UI.

What It Does

Dictos helps you build a personal Dictionary from text you care about.

• Entries - Words, phrases, or sentences saved from reading or entered manually.
• Descriptions - Explanations, translations, examples, or other text attached to an Entry.
• Folders - Nested containers for organizing Entries.
• Instructions - Reusable templates for generating Descriptions with an LLM API.
• Sync - Local-first replication across your devices.
• Export - Planned output to external formats such as Anki, JSON, or your favorite learning app.

See CONTEXT.md for the project vocabulary. The terms are deliberate because they shape the domain model and UI.

Status

Dictos is intended to become a serious open-source app for outside users, but it is not polished enough for casual users yet.

Current state:

• Terminal UI is the primary client.
• Web client exists and is being developed.
• Central server exists for auth, sync setup, and future social features.
• Mobile is part of the longer-term architecture, not the current product surface.
• APIs, storage details, and UX can still change hard.

Features

• Local-first data - Your Dictionary lives locally and should keep working offline.
• Keyboard-first workflow - The TUI is built for fast navigation and editing.
• Cross-platform architecture - Shared domain and headless UI logic are reused across clients.
• Turso database - Local persistence with sync-oriented database adapters.
• Headless React controller - @dictos/react owns shared interaction state while clients render their own UI.
• Server-backed sync setup - The central ElysiaJS server supports auth and database provisioning flows.

Requirements

Recommended:

• devenv 2.x
• Nix, as required by devenv

Provided by devenv shell:

• Bun
• Turso CLI / tursodb
• SecretSpec
• GitHub CLI
• Development environment variables
• Local process wiring for the Web client, server, and sync server
• Additional file strcture setup

Manual setup is possible, but you must recreate the work that devenv automates. That means installing the tools above, setting the environment variables, configuring secrets, creating expected local data directories, running the local sync server, and starting each process yourself.

Development

Enter the development environment first:

devenv shell

Install dependencies:

bun install

Run the Terminal UI:

bun run dev:tui

Run the Web client:

bun run dev:web

Run the central server:

bun run dev:server

Run the full local Web/server/sync stack managed by devenv:

devenv up

Typecheck the monorepo:

bun run typecheck

Secrets

Dictos uses SecretSpec through devenv.

If this is your first time entering the shell, initialize a SecretSpec backend when prompted:

secretspec config init

Then check or fill missing secrets:

secretspec check

Development defaults are declared in secretspec.toml. Production-like server flows need real values.

Variable	Purpose	Development default
JWT_SECRET	Signs auth tokens	Generated by SecretSpec
TURSO_ORG_SLUG	Turso organization slug	local-dev-org
TURSO_PLATFORM_TOKEN	Turso Platform API token	Local placeholder
TURSO_SYNC_URL	Local sync server URL	http://localhost:8080
TURSO_DATABASE_URL	Central server database URL	file:.data/central-server.db
TURSO_AUTH_TOKEN	Auth token for remote Turso database	unset
PORT	Central server port	1488

Manual Setup Notes

Use devenv if you can.

Without devenv:

• read devenv.nix to figure out what needs to be done.
• figure it out
• ask Roverp1 for help

Project Structure

apps/tui/                 Terminal UI client using OpenTUI + React
apps/web/                 Web client using Vite + React Router
apps/server/              ElysiaJS central server
packages/core/            Pure domain logic, ports, and services
packages/react/           Headless shared UI state and actions
packages/db-core/         Shared Drizzle schema and repositories
packages/bun-turso-sync/  Bun/local Turso sync adapter
packages/wasm-turso-sync/ Browser/WASM Turso sync adapter
packages/fs-storage/      Filesystem storage adapter
packages/local-storage/   Browser localStorage adapter
packages/eden-http/       Elysia Eden HTTP client adapter
packages/logger/          Shared logger interface
packages/pino-logger/     Pino logger adapter

Architecture

Dictos uses a hexagonal architecture.

The core domain lives in packages/core and must not depend on React, UI frameworks, database drivers, logging implementations, or platform APIs. Infrastructure details are pushed into adapters and injected through ports.

@dictos/react is a headless controller shared by clients. It owns cross-platform Dictionary interaction state such as browse mode, entry mode, preview content, cursors, selection, and context-menu targets. The TUI and Web clients decide how that state is rendered and how input is bound.

For the full architecture, read docs/system-overview.md.

Documentation

• docs/system-overview.md - Purpose, architecture, stack, and codebase map.
• CONTEXT.md - Project terminology.
• docs/testing.md - Testing strategy and rules.
• docs/adr - Architecture decisions.

Troubleshooting

devenv shell is not available

Install devenv using the official guide: https://devenv.sh/getting-started/.

If you do not want to use devenv, follow the manual setup notes and expect extra work. The repo assumes devenv during development.

SecretSpec says secrets are missing

Initialize a backend and fill the required secrets:

secretspec config init
secretspec check

Web sync requests fail locally

The Web client proxies sync endpoints to http://localhost:8080. Start the local sync server with devenv up.

Contributing

Contributions are extremely welcome, but the project is still moving quickly. For larger changes, open an issue first.

Before changing domain or architecture code, read:

• CONTEXT.md
• docs/system-overview.md
• docs/testing.md

For questions, open a GitHub issue or contact Yaroslav Gulevsky at yar.zubaha@proton.me.

AI Policy

All the main production code is currently written by hand, with AI being used only for assistance. The current web app is an exception, as it was fully generated from the tui app, for exploration purposes, and will require full human rewrite, before it will be considered production ready. Also all of the documentation (including github issues, and pr's) are mostly generated with AI, but fully review, and lightly edited, to keep it factual. As the project grows - the documentation will need to be rewritten by a human, and will have a higher quality enforcment.

For more information read AI Policy (adapted from Ghosty AI Policy)

License

Dictos is licensed under the GNU Affero General Public License v3.0. See LICENSE.