Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Nucleus repository contains an open-source library that powers a suite of personal productivity and well-being applications developed by 21n.org. The project is structured as a monorepo to manage shared code and individual product applications efficiently. The primary products built from this repository are Nucleus (a super app), Memotron (a knowledge management tool), and Pointron (a focus and time management tool).
The architecture emphasizes a clear separation between frontend clients and a backend server, with a strong focus on shared libraries for UI components, utilities, and types. The frontend is built with SvelteKit and TailwindCSS, while the backend uses Node.js. A key principle is the offline-first approach, ensuring applications are fully functional without an internet connection.
Sources: README.md:5-7, WARP.md:5-12, client/landing/routes/compare/memotronWheel.ts:241-248
Monorepo Structure
The project utilizes a monorepo architecture managed by Turbo for build orchestration. This structure facilitates code sharing and streamlined development across different products and libraries. The test-setup.js script verifies the existence of key packages and product app directories, ensuring the integrity of the workspace setup.
Sources: WARP.md:14-27, test-setup.js:1-72
The diagram below illustrates the high-level directory structure of the monorepo.
This diagram shows the main directories within the monorepo and their sub-directories.
Sources: WARP.md:15-27, test-setup.js:24-34, 41-50
The key directories and their purposes are summarized in the table below:
| Directory | Description |
|---|---|
client/ | Contains frontend code and product-specific implementations. |
client/products/ | Houses the individual product applications like Nucleus, Memotron, etc. |
packages/ | Contains shared libraries for components, types, utilities, and more. |
server/ | Holds the backend API and database logic. |
shared/ | Contains code shared between the client and server, such as types and utils. |
deployment/ | Includes deployment configurations and scripts. |
tests/ | Contains test files for the applications and packages. |
Sources: WARP.md:15-27
Product Suite
The repository is the foundation for several distinct productivity tools, all intended for personal use without team collaboration features.
| Name | Website | Description | Topics |
|---|---|---|---|
| Nucleus | nucleus.to | Your digital harmony, a super app that combines all the tools below. | Digital life, personal productivity |
| Memotron | memotron.app | Your memory atlas, a tool for managing your knowledge. | PKM, note‑taking, knowledge management |
| Pointron | pointron.app | Your focus haven, a tool for tracking goals and managing your time. | Focus, time management |
Sources: README.md:14-24, WARP.md:6-10
Each product has its own configuration file (client/products/product.config.ts) that defines its specific menus, settings, resources, and features.
Sources: WARP.md:30-31
Technology Stack
The project leverages a modern technology stack for both frontend and backend development.
| Category | Technology | Description |
|---|---|---|
| Frontend | SvelteKit, TailwindCSS | Used for building the client-side applications. |
| Backend | Node.js | Powers the server-side API. |
| Build System | Turbo | Used for build orchestration and task running across the monorepo. |
| Database | SurrealDB, Dexie, LocalForage | SurrealDB is used for the main database, while Dexie and LocalForage provide local storage solutions to support the offline-first approach. |
Sources: README.md:46-47, WARP.md:12, 32-37
Key Architectural Concepts
Offline-First Approach
A core design principle is "Offlinability," which ensures a fully functional offline version of the applications. This is achieved through local-first data storage using technologies like Dexie and LocalForage, with synchronization occurring when an online connection is available.
Sources: client/landing/routes/compare/memotronWheel.ts:241-248, client/cx/contemporaries/notion.json:60-63, WARP.md:36-37
Resource System
The products are designed to work with various resource types, which form the data model of the applications. These include:
- nodes
- relations
- goals
- tasks
- events
- collections
- combinations
Sources: WARP.md:32-33
Open Source and Sustainability
The project is fully open-source under the AGPL-3.0 license, with a transparent development process. A key goal is long-term sustainability, which includes plans for enabling self-hosting and ensuring data portability to avoid vendor lock-in.
Sources: README.md:9, 49, client/landing/routes/compare/memotronWheel.ts:72-87, 212-231
Build and Development
Turbo orchestrates the build and development workflows. A set of npm scripts are defined to manage tasks for the entire monorepo or for specific products.
The diagram below shows the flow for starting a development environment.
This diagram shows how the npm run dev command uses Turbo to start all product apps.
Sources: WARP.md:42-47
Common Commands
npm run dev: Starts all applications in development mode.npm run build: Builds all packages and applications.npm run test: Runs all tests.npm run lint: Runs the linter.
Specific products can be targeted, for example: npm run dev:nucleus or npm run build:nucleus.
Sources: WARP.md:43-63
Deployment
Self-Hosting
Currently, only the frontend applications can be self-hosted. This provides an offline-only version of the app at a user-defined URL. Full-stack deployment, including the backend on Cloudflare infrastructure (Workers, D1, R2), is planned for the future.
To deploy the frontend, the following steps are required:
- Clone the repository.
- Choose a product app from the
/apps(an alias forclient/products) folder. - Set the required environment variables.
- Deploy to a hosting provider.
VITE_PRODUCT={{memotron | pointron | nucleus }}
VITE_STATIC_URL=https://cdn.21n.co
Sources: README.md:28-42
CI/CD
The project documentation suggests using GitLab CI/CD for continuous integration and deployment. It outlines capabilities for:
- Static Application Security Testing (SAST).
- Automated deployment to Kubernetes, Amazon EC2, or Amazon ECS.
- Setting up protected environments.
Sources: deployment/README.md:28-34