Initial commit: Ultimate Notetaking, Sync & Backup System
A NixOS-based system for managing personal data across three tiers: - Tier 1: Configuration (shareable via git) - Tier 2: Syncable data (nb + Syncthing) - Tier 3: Large data (self-hosted services + backup) Includes: - NixOS modules for nb, Syncthing, backup (restic) - Server modules for Forgejo, Immich, Jellyfin - Helper scripts (usync, ustatus) - Comprehensive documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
240
docs/LLM-CONTEXT.md
Normal file
240
docs/LLM-CONTEXT.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user