Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Fixius50/WorlBuilding-Writting-App/llms.txt

Use this file to discover all available pages before exploring further.

Chronos Atlas is built on a hybrid local-first architecture where the React/TypeScript frontend is the sovereign owner of all application data, and the Java auxiliary backend acts purely as an on-demand helper worker. This inversion of the traditional web model means the application is fully operational without any server connection — the backend exists to extend capability, not to enable it. Data lives in your browser’s private filesystem. The server provides compute.

​
The Two-Layer Stack

The responsibilities of each layer are strictly separated. Nothing that belongs in the frontend leaks into the backend, and the backend never holds authoritative application state.
ConcernFrontend (React + Vite)Backend (Java + Jetty)
RuntimeReact 19, TypeScript 5.7, Vite 6Java 21, Spring Web MVC 5.3.31, embedded Jetty
Data ownershipAll worldbuilding data — entities, maps, timelines, writing, linguisticsNone; stateless between requests
PersistenceSQLite WASM (SQLocal) inside OPFSReal filesystem via bridge endpoints
State managementZustand stores, TanStack Query cacheN/A
Offline capabilityFully functionalNot applicable
Typical tasksRendering, editing, querying SQLite, graph operationsFilesystem backups, PDF/font export, filesystem-level snapshots
Failure modeFrontend failure is isolated to the UI layerIf down, only heavy export features are disabled; all editing continues

​
Frontend Runtime Flow

When a user performs an action in the app — creating an entity, editing a timeline event, drawing a map region — the data flows through a strict layered pipeline entirely within the browser. No server round-trip is required. The four stages of this pipeline are:
  1. View (pages/ and components/) — React components capture user input and render application state. They delegate all business logic to use cases and consume state through hooks.
  2. UseCase (application/) — Orchestrates business operations without coupling to visual details. A use case coordinates domain rules and calls the infrastructure layer to persist or retrieve data.
  3. Infrastructure (src/infrastructure/) — The only layer that knows how data is actually stored or fetched. It contains two sub-paths:
    • localDB/ — SQLocal repositories that send SQL to a Web Worker executing SQLite WASM in OPFS.
    • network/ — HTTP clients that communicate with the Java auxiliary backend when needed.
  4. SQLite WASM in OPFS — The authoritative store. All writes are persisted as binary SQLite data in the browser’s Origin Private File System.
Components and hooks inside features/ must never issue SQL queries directly. All data access must go through the repository layer at src/infrastructure/localDB/repositories/, imported via the @repositories/* alias. Bypassing this rule breaks the separation of concerns that makes the architecture maintainable and testable.

​
Feature-Sliced Architecture

The frontend is organized as vertical slices, where each product domain — Entities, Maps, Timelines, Writing, Linguistics, Graph, Shell — is an independent feature that encapsulates all its own layers.

​
Standard Folder Structure per Feature

Each feature lives under src/features/<FeatureName>/ and may contain any of these directories as needed:
DirectoryPurpose
application/Use cases and business orchestration logic. No UI imports.
components/Visual components reusable within this feature only.
hooks/Hooks shared across multiple components or pages within the feature.
pages/Route-level views. Screen-specific hooks are co-located here, not in hooks/.
domain/TypeScript types, interfaces, and domain contracts.
store/Feature-scoped Zustand state.
Not every feature requires every folder. Only create a directory when there are files that justify it. The index.ts at the root of each feature is its public API contract. Other features must import from @features/<FeatureName> only — never from internal subdirectories like @features/Entities/components/SomeComponent.

​
The Shared Kernel

src/features/Shared/ is a cross-cutting UI kernel — not a business logic container. It provides primitives, navigation components, modals, panels, feedback widgets, and visual utilities that any feature may consume. Business-level integrations that must temporarily pass through Shared are declared explicitly in Shared/adapters/ to remain visible and auditable.

​
When the Backend Is Optional

A core design guarantee of Chronos Atlas is graceful backend absence. If the Java auxiliary server is not running or fails to start:
  • Writing and editing prose in the Writing Hub continues normally.
  • Creating, reading, updating, and deleting entities works without interruption.
  • The Relationship Graph remains fully interactive — nodes and edges can be added, moved, and deleted.
  • World Bible documents, timeline events, and map annotations are all readable and editable.
  • Conlang/linguistics data remains accessible.
Only the following capabilities are blocked when the backend is unavailable:
  • Filesystem backup snapshots — writing .sqlite copies to the real filesystem via the bridge endpoint.
  • Heavy export operations — PDF generation (Flying Saucer) and any server-side compilation tasks.
This separation is intentional. The frontend must remain sovereign over data. The server is a worker, never a gatekeeper.

​
Path Aliases

The frontend Vite configuration defines a set of path aliases that enforce clean import boundaries and insulate features from internal path changes. All imports inside src/ should use these aliases rather than relative paths that cross layer or feature boundaries.
AliasResolves ToUsage
@featuressrc/featuresRoot of the features directory
@componentssrc/features/SharedImporting from the Shared kernel (e.g. @components/primitives)
@contextsrc/features/App/contextApplication-level React contexts (active workspace, project ID, etc.)
@databasesrc/infrastructure/localDB/clientThe SQLocal sqlocal instance and sql tag
@infrastructuresrc/infrastructureFull infrastructure layer root
@repositoriessrc/infrastructure/localDB/repositoriesRepository service modules (@repositories/entityService, etc.)
@networksrc/infrastructure/networkNetwork clients (@network/syncService, etc.)
@utilssrc/infrastructure/utilsShared utility functions
@domain/databasesrc/features/App/domain/databaseCore domain types (Entidad, Proyecto, Carpeta, etc.)
@domain/mapssrc/features/Maps/domain/mapsMap-specific domain types
@domain/timelinesrc/features/Timeline/domain/timelineTimeline domain types
@domain/writingsrc/features/Writing/domain/writingWriting/notebook domain types
@domain/linguisticssrc/features/Linguistics/domain/linguisticsLinguistics/conlang domain types
@domain/graphsrc/features/Graph/domain/graphGraph domain types
@domain/uisrc/features/Shell/domain/uiShell/UI domain types
Shared kernel imports use @components — there is no ui segment in the path. Importing @components/ui/Button is incorrect; the right form is @components/primitives/Button (or whichever Shared subdirectory applies). Individual @domain/* aliases are declared explicitly in vite.config.ts — there is no single catch-all @domain/* wildcard.

​
Architecture Guardrails

Two automated checks enforce these boundaries at any time during development: 
# Non-breaking report — safe to run locally
npm run arch:check

# Strict mode — exits with error if violations are found (CI use)
npm run arch:check:strict
Both commands write results to frontend/reports/architecture-guard-report.json. The rules verified are:
  1. No deep cross-feature imports — a feature must not import internal subdirectories of another feature.
  2. No business logic in Shared outside of Shared/adapters — the Shared kernel must remain a pure UI utility layer.

Build docs developers (and LLMs) love

Get started for freeTalk to us