grapho/docs/LLM-CONTEXT.md

LLM Context Document

This document provides context for AI assistants (Claude, GPT, Copilot, etc.) working with this codebase.

Project Overview

Name: Ultimate Notetaking, Sync & Backup System Purpose: NixOS-based declarative system for managing personal data across multiple machines Primary User: Linux users, especially NixOS, who want full control over their data

Core Concepts

The Three-Tier Data Model

TIER 1: Configuration (Shareable)
├── What: System config, dotfiles, flake.nix
├── Where: This git repo (public on GitHub)
├── How: NixOS + home-manager + sops-nix
└── Philosophy: Anyone can clone and use this config

TIER 2: Syncable Data (Private, Multi-device)
├── What: Notes, documents, writings
├── Where: ~/notes/ (nb), ~/Documents/ (Syncthing)
├── How: nb (git-backed) for text, Syncthing for binary
└── Philosophy: Edit anywhere, sync automatically

TIER 3: Large Data (Backed up, On-demand)
├── What: Photos, videos, large repos
├── Where: Self-hosted servers (Immich, Jellyfin, Forgejo)
├── How: Upload to server, access on-demand, restic backup
└── Philosophy: Don't sync everything; backup everything

Key Tools

Tool	Purpose	Tier
NixOS	Declarative system configuration	1
home-manager	Declarative user configuration	1
sops-nix	Encrypted secrets in git	1
nb	CLI notebook with git sync	2
Syncthing	P2P file synchronization	2
Neovim	Primary editor	1, 2
Forgejo	Self-hosted git (GitHub alternative)	3
Immich	Self-hosted photos (Google Photos alternative)	3
Jellyfin	Self-hosted media (Plex alternative)	3
restic	Encrypted, deduplicated backups	3
rclone	Cloud storage Swiss Army knife	3

File Structure

flake.nix              # Nix flake entry point
├── inputs: nixpkgs, home-manager, sops-nix
├── outputs: nixosConfigurations, homeConfigurations, devShells
└── imports modules for each host

modules/
├── nb.nix             # nb installation and config
├── syncthing.nix      # Declarative Syncthing
├── neovim.nix         # Neovim with nb integration
├── backup.nix         # restic systemd timers
└── server/            # Server-only modules
    ├── forgejo.nix
    ├── immich.nix
    └── jellyfin.nix

hosts/
├── desktop/           # Desktop-specific config
├── laptop/            # Laptop-specific config
└── server/            # Server-specific config

home/
└── default.nix        # home-manager user config

scripts/
├── usync              # Unified sync (nb + Syncthing)
├── ubackup            # Manual backup trigger
└── ustatus            # Status dashboard

Common Tasks

User wants to add a new notebook

1. Edit modules/nb.nix
2. Add notebook to programs.nb.notebooks
3. Run nixos-rebuild switch
4. Run nb notebooks to verify

User wants to add a Syncthing folder

1. Edit modules/syncthing.nix
2. Add folder to services.syncthing.settings.folders
3. Add device IDs if new devices
4. Run nixos-rebuild switch

User wants to change backup paths

1. Edit modules/backup.nix
2. Modify services.restic.backups.default.paths
3. Run nixos-rebuild switch

User wants to add a new host

1. Create hosts/<hostname>/configuration.nix
2. Add to flake.nix outputs
3. Configure host-specific settings
4. Run nixos-rebuild switch --flake .#<hostname>

Code Patterns

Module Structure

All modules follow this pattern:

{ config, lib, pkgs, ... }:

with lib;

let
  cfg = config.services.ourService;
in {
  options.services.ourService = {
    enable = mkEnableOption "our service";

    someOption = mkOption {
      type = types.str;
      default = "default-value";
      description = "Description of the option";
    };
  };

  config = mkIf cfg.enable {
    # Implementation
  };
}

Home-manager Integration

User-level config uses home-manager:

{ config, pkgs, ... }:

{
  programs.git = {
    enable = true;
    userName = "User Name";
    userEmail = "user@example.com";
  };
}

Secrets Management

Secrets use sops-nix:

{
  sops.secrets.syncthing-key = {
    sopsFile = ./secrets/secrets.yaml;
    owner = "user";
  };
}

Constraints

1. Open source only: No proprietary tools
2. NixOS-centric: Must work with nixos-rebuild
3. Flakes required: All Nix code uses flakes
4. No cloud dependencies: Must work fully self-hosted (cloud optional)
5. CLI-first: GUI is optional, never required
6. Markdown for notes: Plain text, portable, version-control friendly

When Helping Users

DO:

• Suggest declarative (Nix) solutions
• Recommend nb for text/notes
• Recommend Syncthing for binary files
• Use systemd for services
• Use home-manager for user config
• Keep modules composable

DON'T:

• Suggest proprietary alternatives
• Hardcode paths (use options)
• Mix system and user config inappropriately
• Ignore the three-tier model
• Suggest Syncthing for notes (use nb instead)

Debugging

Common Issues

Symptom	Likely Cause	Solution
nb sync fails	SSH key not available	Check ssh-add -l
Syncthing not starting	Declarative config conflict	Check for GUI-made changes
Backup fails	Repository not initialized	Run restic init
Module not found	Not imported in flake.nix	Add to imports

Useful Commands

# Check Nix config
nix flake check

# Show Syncthing status
syncthing cli show system

# nb sync status
nb sync status

# restic backup status
restic -r <repo> snapshots

Extension Points

Users commonly want to extend:

1. Additional notebooks: Add to modules/nb.nix
2. New Syncthing folders: Add to modules/syncthing.nix
3. Backup exclusions: Modify modules/backup.nix
4. Server services: Add new modules under modules/server/
5. Editor config: Modify modules/neovim.nix

Related Documentation

• Architecture - Detailed system design
• Sync Tools Comparison - Why we chose these tools
• nb documentation
• NixOS manual
• home-manager manual