Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• WARP.md
• deployment/README.md
• client/landing/routes/compare/memotronWheel.ts
• client/landing/memotron.io/compare/memotronWheel.ts
• client/cx/contemporaries/notion.json

Welcome to the contributing guide for Nucleus (also referred to as Tidigit). This project is an open-source library that powers a suite of personal productivity and well-being applications. We welcome contributions from the community to help improve the tools.

The technology stack primarily consists of SvelteKit and TailwindCSS for the frontend client, and Node.js for the backend. The project and all contributions are licensed under the AGPL-3.0 license.

Sources: README.md:5-6, 45-46, 50-51, CONTRIBUTING.md:3, 27-28

Project Overview

The repository is a monorepo containing several distinct but related productivity tools. Understanding the overall architecture is key to contributing effectively.

Tools

The following tools are built using this repository:

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:16-26, WARP.md:8-13

Architecture

The project utilizes a monorepo architecture managed with Turbo for build orchestration.

This diagram shows the high-level directory structure of the monorepo.

Key Architectural Concepts:

• Monorepo Structure: The code is organized into logical directories:
  • client/: Contains frontend code and product-specific implementations.
  • packages/: Houses shared libraries like components, types, and utils.
  • server/: Backend API and database logic.
  • shared/: Code shared between the client and server.
  • deployment/: Configurations for deployment.
  • tests/: Test files.
• Product Configuration: Each product has its own configuration file (e.g., client/products/product.config.ts) that defines its specific menus, settings, and features.
• Database: The backend uses SurrealDB, while local storage solutions like Dexie and LocalForage are used on the client side.

Sources: WARP.md:17-29

Getting Started

This section guides you through setting up your local development environment.

Initial Setup Flow

The following diagram illustrates the steps to prepare your environment for contributing.

Setup Steps

1. Fork the Repository: Start by forking the 21nOrg/client repository.
   Sources: CONTRIBUTING.md:7
2. Clone Your Fork: Clone the forked repository to your local machine.

   git clone <your-fork-url>
   

   Sources: CONTRIBUTING.md:8
3. Install Dependencies: Navigate to the repository directory and install the necessary dependencies.

   npm install
   

   Sources: CONTRIBUTING.md:9
4. Create a New Branch: Create a new branch for your feature or bug fix.

   git checkout -b feature/your-feature-name
   

   Sources: CONTRIBUTING.md:10
5. Configure Environment Variables: Set the following environment variables. These are necessary to run the application.

   VITE_PRODUCT=memotron
   VITE_STATIC_URL=https://cdn.21n.co
   

   Sources: CONTRIBUTING.md:11-15

Development Workflow

The monorepo is managed using npm scripts orchestrated by Turbo.

Common Commands

These commands are run from the root of the repository.

Command	Description
npm run dev	Start all apps in development mode.
npm run dev:nucleus	Start only the Nucleus app.
npm run build	Build all packages and apps.
npm run test	Run all tests.
npm run lint	Run linting across the codebase.
npm run clean	Clean build artifacts.

Sources: WARP.md:34-48

Single Product Development

When working on a single product, you can navigate to its directory for a more focused workflow. For example, to work on Nucleus:

cd client/products/nucleus

The following commands are available within a product's directory:

Command	Description
npm run dev	Start development server on port 5050.
npm run debug	Start development server on host 0.0.0.0:5050.
npm run debug-pre	Run in 'pre' environment mode.
npm run debug-live	Run in 'live' environment mode.
npm run build	Create a production build.
npm run build-pre	Build for the 'pre' environment.
npm run build-live	Build for the 'live' environment.
npm run test	Run tests.

Sources: WARP.md:53-69

Code and Contribution Standards

To maintain code quality and a consistent development process, please adhere to the following standards.

Coding Rules

• No Inline Comments: Do not add inline comments when generating or editing code. The code should be self-explanatory.
  Sources: WARP.md:74-77

Submitting a Pull Request

1. Push your changes to your forked repository.
2. Submit a pull request to the main repository.

Sources: CONTRIBUTING.md:18-20

Pull Request Review Fixing Protocol

When asked to fix issues from a pull request review, follow this systematic process to ensure all feedback is addressed.

This sequence diagram shows the workflow for addressing PR review comments.

Steps for Fixing PR Reviews:

1. Initial Data Fetch: Use the GitHub CLI to fetch all review data for the PR.
2. Comprehensive Data Collection: If CLI data is insufficient, use a headless browser (e.g., Playwright) to scrape the entire PR page. All scraping tools and scripts must be in a temporary directory (e.g., /tmp/pr_review/) and not committed to the project.
3. Critical Issue Analysis: Identify all actionable comments from all review sources, including Sourcery AI, CodeRabbit AI, Typo-app, Cubic AI, and human reviewers.
4. Systematic Resolution: Create a comprehensive to-do list and fix each issue methodically.

Sources: WARP.md:81-118

Understanding the Codebase

To contribute effectively, it's helpful to understand how key entities like features and competitor data are structured.

Feature Definition

Features are defined as an array of objects conforming to the IFwFeature type. This structure is used, for example, in the Memotron feature comparison wheel.

// client/landing/routes/compare/memotronWheel.ts

export const features: IFwFeature[] = [
  // App features
  {
    label: "Source",
    slug: "source",
    category: MemotronFeatureCategory.App,
    icon: "source",
    learnMoreLink: "https://docs.memotron.app/memotron/source",
    progress: 1,
    isProminent: true,
    description:
      "Source available codebase allowing public access and contributions with transparent development process",
    ratingCriteria: [
      {
        label: "Open source or source code is available",
        slug: "open-source",
        icon: "ph:code-light"
      },
      // ... more criteria
    ],
    // ... more properties
  },
  // ... more features
];

Sources: client/landing/routes/compare/memotronWheel.ts:50-78, client/landing/memotron.io/compare/memotronWheel.ts:50-78

Competitor Data Structure

Data for comparing features with contemporary applications is stored in JSON files. This allows for a structured way to manage ratings and notes for each competitor.

// client/cx/contemporaries/notion.json

{
  "label": "Notion",
  "url": "notion.so",
  "icon": "svg:notion",
  "sourcingType": "CLOSED",
  "features": [
    {
      "feature": "source",
      "rating": 0
    },
    {
      "feature": "privacy",
      "rating": 0.3,
      "notes": "Notion doesn't take offline-first approach and does not have end-to-end encryption for cloud sync..."
    },
    // ... more feature ratings
  ]
}

Sources: client/cx/contemporaries/notion.json:1-21

Reporting Issues

If you discover a bug or have a suggestion, please report it in the issues section of the repository. Providing clear and detailed information will help us address it more effectively.

Sources: CONTRIBUTING.md:23-24, deployment/README.md:68-69

License

By contributing to this project, you agree that your contributions will be licensed under the AGPL-3.0 license.

Sources: CONTRIBUTING.md:27-28, README.md:50-51