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:

```nix
{ 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:

```nix
{ config, pkgs, ... }:

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

### Secrets Management

Secrets use sops-nix:

```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

```bash
# 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](./ARCHITECTURE.md) - Detailed system design
- [Sync Tools Comparison](./research/sync-tools-comparison.md) - Why we chose these tools
- [nb documentation](https://xwmx.github.io/nb/)
- [NixOS manual](https://nixos.org/manual/nixos/stable/)
- [home-manager manual](https://nix-community.github.io/home-manager/)