|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with |
| 4 | +code in this repository. |
4 | 5 |
|
5 | 6 | ## Project Overview |
6 | 7 |
|
7 | | -Zit is a Zettelkasten-style knowledge management system written in Go. It provides Git-like version control for managing interconnected notes (Zettels) with content-addressable storage, sophisticated querying, and remote synchronization capabilities. |
| 8 | +Dodder is a Zettelkasten-style knowledge management system written in Go. It |
| 9 | +provides Git-like version control for managing interconnected notes (Zettels) |
| 10 | +with content-addressable storage, sophisticated querying, and remote |
| 11 | +synchronization capabilities. |
8 | 12 |
|
9 | 13 | ## Build and Development Commands |
10 | 14 |
|
11 | 15 | ### Core Development Tasks |
12 | | -- **Build**: `just build` (builds binary to `build/zit`) |
13 | | -- **Test**: `just test` (runs Go unit tests + BATS integration tests) |
14 | | -- **Unit Tests Only**: `just test-go-unit` or `go test -v ./...` |
15 | | -- **Single Package Test**: `go test -v ./src/path/to/package` |
16 | | -- **Clean**: `just clean` (clears Go caches) |
17 | | -- **Check**: `just check` (vulnerability scan + vet) |
18 | | -- **Generate**: `just build-go-generate` (runs `go generate ./...`) |
| 16 | + |
| 17 | +- **Build**: `just build` (builds binary to `build/dodder`) |
| 18 | +- **Test**: `just test` (runs Go unit tests + BATS integration tests) |
| 19 | +- **Unit Tests Only**: `just test-go-unit` or `go test -v ./...` |
| 20 | +- **Single Package Test**: `go test -v ./src/path/to/package` |
| 21 | +- **Clean**: `just clean` (clears Go caches) |
| 22 | +- **Check**: `just check` (vulnerability scan + vet) |
| 23 | +- **Generate**: `just build-go-generate` (runs `go generate ./...`) |
19 | 24 |
|
20 | 25 | ### Code Quality |
21 | | -- **Format**: `just codemod-go-imports` (runs goimports on all Go files) |
22 | | -- **Vulnerability Check**: `just check-go-vuln` |
23 | | -- **Go Vet**: `just check-go-vet` |
| 26 | + |
| 27 | +- **Format**: `just codemod-go-imports` (runs goimports on all Go files) |
| 28 | +- **Vulnerability Check**: `just check-go-vuln` |
| 29 | +- **Go Vet**: `just check-go-vet` |
24 | 30 |
|
25 | 31 | ### Alternative Build Systems |
26 | | -- **Nix**: `just build-nix` (requires Nix with flakes) |
27 | | -- **Docker**: `just build-docker` |
| 32 | + |
| 33 | +- **Nix**: `just build-nix` (requires Nix with flakes) |
| 34 | +- **Docker**: `just build-docker` |
28 | 35 |
|
29 | 36 | ## Architecture Overview |
30 | 37 |
|
31 | 38 | ### NATO Phonetic Module Organization |
32 | | -The codebase uses NATO phonetic alphabet naming for layered architecture with strict dependency ordering (each layer can only depend on previous layers): |
33 | | - |
34 | | -- **alfa**: Foundation (errors, interfaces, primitives) |
35 | | -- **bravo**: Basic utilities (UI, pools, values, flags) |
36 | | -- **charlie**: Collections and data structures (sets, I/O, files) |
37 | | -- **delta**: Data processing (SHA, strings, Lua VM, encryption) |
38 | | -- **echo**: Object identification and metadata systems |
39 | | -- **foxtrot**: Configuration and workspace management |
40 | | -- **golf**: Command framework and object metadata |
41 | | -- **hotel**: Repository and environment management |
42 | | -- **india**: Indexing and search systems |
43 | | -- **juliett**: SKU (core object management and storage) |
44 | | -- **kilo**: Query system and object formatting |
45 | | -- **lima**: Storage engines and text organization |
46 | | -- **mike**: Main store implementation |
47 | | -- **november**: Local working copy management |
48 | | -- **oscar**: Remote operations and HTTP API |
49 | | -- **papa**: User operations and command components |
50 | | -- **quebec**: CLI command definitions |
| 39 | + |
| 40 | +The codebase uses NATO phonetic alphabet naming for layered architecture with |
| 41 | +strict dependency ordering (each layer can only depend on previous layers): |
| 42 | + |
| 43 | +- **alfa**: Foundation (errors, interfaces, primitives) |
| 44 | +- **bravo**: Basic utilities (UI, pools, values, flags) |
| 45 | +- **charlie**: Collections and data structures (sets, I/O, files) |
| 46 | +- **delta**: Data processing (SHA, strings, Lua VM, encryption) |
| 47 | +- **echo**: Object identification and metadata systems |
| 48 | +- **foxtrot**: Configuration and workspace management |
| 49 | +- **golf**: Command framework and object metadata |
| 50 | +- **hotel**: Repository and environment management |
| 51 | +- **india**: Indexing and search systems |
| 52 | +- **juliett**: SKU (core object management and storage) |
| 53 | +- **kilo**: Query system and object formatting |
| 54 | +- **lima**: Storage engines and text organization |
| 55 | +- **mike**: Main store implementation |
| 56 | +- **november**: Local working copy management |
| 57 | +- **oscar**: Remote operations and HTTP API |
| 58 | +- **papa**: User operations and command components |
| 59 | +- **quebec**: CLI command definitions |
51 | 60 |
|
52 | 61 | ### Core Domain Model |
53 | 62 |
|
54 | 63 | #### Key Concepts |
55 | | -- **Zettels**: Fundamental content units with unique IDs and metadata |
56 | | -- **SKUs (Stock Keeping Units)**: Versioned objects representing all content types |
57 | | -- **Object IDs**: Three-part identifiers with genre/type information |
58 | | -- **Content-Addressable Storage**: SHA-based blob storage with inventory tracking |
59 | | -- **Tags and Types**: Hierarchical organization system |
60 | | -- **Working Copy**: Git-like checked-out file system |
| 64 | + |
| 65 | +- **Zettels**: Fundamental content units with unique IDs and metadata |
| 66 | +- **SKUs (Stock Keeping Units)**: Versioned objects representing all content |
| 67 | + types |
| 68 | +- **Object IDs**: Three-part identifiers with genre/type information |
| 69 | +- **Content-Addressable Storage**: SHA-based blob storage with inventory |
| 70 | + tracking |
| 71 | +- **Tags and Types**: Hierarchical organization system |
| 72 | +- **Working Copy**: Git-like checked-out file system |
61 | 73 |
|
62 | 74 | #### Critical Types and Interfaces |
63 | | -- `sku.Transacted`: Core versioned object type (src/juliett/sku/) |
64 | | -- `interfaces.ObjectId`: Universal identifier interface (src/alfa/interfaces/) |
65 | | -- `store.Store`: Main storage engine (src/mike/store/) |
66 | | -- `command.Command`: CLI command interface (src/golf/command/) |
| 75 | + |
| 76 | +- `sku.Transacted`: Core versioned object type (src/juliett/sku/) |
| 77 | +- `interfaces.ObjectId`: Universal identifier interface (src/alfa/interfaces/) |
| 78 | +- `store.Store`: Main storage engine (src/mike/store/) |
| 79 | +- `command.Command`: CLI command interface (src/golf/command/) |
67 | 80 |
|
68 | 81 | ### Storage Architecture |
69 | | -- **Blob Store**: Content-addressable binary storage |
70 | | -- **Inventory Lists**: Object metadata and relationship tracking |
71 | | -- **Stream Index**: Binary indexing for fast object access |
72 | | -- **Zettel ID Index**: Specialized indexing for note relationships |
73 | | -- **Dormant Index**: Inactive/archived object tracking |
| 82 | + |
| 83 | +- **Blob Store**: Content-addressable binary storage |
| 84 | +- **Inventory Lists**: Object metadata and relationship tracking\ |
| 85 | +- **Stream Index**: Binary indexing for fast object access |
| 86 | +- **Zettel ID Index**: Specialized indexing for note relationships |
| 87 | +- **Dormant Index**: Inactive/archived object tracking |
74 | 88 |
|
75 | 89 | ### Command System |
76 | | -Commands are registered in `src/quebec/commands/` and follow a consistent pattern: |
77 | | -- Flag parsing via `flag.FlagSet` |
78 | | -- Request objects with context and configuration |
79 | | -- Standardized error handling through `alfa/errors` |
| 90 | + |
| 91 | +Commands are registered in `src/quebec/commands/` and follow a consistent |
| 92 | +pattern: - Flag parsing via `flag.FlagSet` - Request objects with context and |
| 93 | +configuration - Standardized error handling through `alfa/errors` |
80 | 94 |
|
81 | 95 | ## Key Development Patterns |
82 | 96 |
|
83 | 97 | ### Error Handling |
84 | | -Uses custom error system in `src/alfa/errors/` with: |
85 | | -- Context-aware error wrapping |
86 | | -- Stack trace support |
87 | | -- Signal handling for graceful shutdown |
88 | | -- Helpful error formatting |
| 98 | + |
| 99 | +Uses custom error system in `src/alfa/errors/` with: - Context-aware error |
| 100 | +wrapping - Stack trace support - Signal handling for graceful shutdown - Helpful |
| 101 | +error formatting |
89 | 102 |
|
90 | 103 | ### Object Lifecycle |
91 | | -1. Objects created as `sku.Proto` (prototype) |
92 | | -2. Transacted through `sku.Transacted` |
93 | | -3. Stored via content-addressable SHA |
94 | | -4. Indexed for query and retrieval |
95 | | -5. Can be checked out to filesystem |
| 104 | + |
| 105 | +1. Objects created as `sku.Proto` (prototype) |
| 106 | +2. Transacted through `sku.Transacted` |
| 107 | +3. Stored via content-addressable SHA |
| 108 | +4. Indexed for query and retrieval |
| 109 | +5. Can be checked out to filesystem |
96 | 110 |
|
97 | 111 | ### Testing Strategy |
98 | | -- Unit tests: `*_test.go` files throughout codebase |
99 | | -- Integration tests: BATS framework in `zz-tests_bats/` |
100 | | -- Test data: Generated fixtures via `test-generate_fixtures` |
| 112 | + |
| 113 | +- Unit tests: `*_test.go` files throughout codebase |
| 114 | +- Integration tests: BATS framework in `zz-tests_bats/` |
| 115 | +- Test data: Generated fixtures via `test-generate_fixtures` |
101 | 116 |
|
102 | 117 | ## Module Import Patterns |
103 | 118 |
|
104 | | -When working with this codebase: |
105 | | -- Import paths follow `code.linenisgreat.com/dodder/go/zit/src/{module}/{package}` |
106 | | -- Respect the NATO alphabet dependency hierarchy |
107 | | -- Use existing interfaces rather than concrete types where possible |
108 | | -- Follow established patterns in similar modules |
| 119 | +When working with this codebase: - Import paths follow |
| 120 | +`code.linenisgreat.com/dodder/go/src/{module}/{package}` - Respect the NATO |
| 121 | +alphabet dependency hierarchy - Use existing interfaces rather than concrete |
| 122 | +types where possible - Follow established patterns in similar modules |
109 | 123 |
|
110 | 124 | ## Important Files for Understanding System |
111 | | -- `main.go`: Application entry point and error handling |
112 | | -- `src/quebec/commands/main.go`: Command dispatch system |
113 | | -- `src/juliett/sku/main.go`: Core object model |
114 | | -- `src/mike/store/main.go`: Primary storage implementation |
115 | | -- `src/november/local_working_copy/main.go`: Working copy management |
| 125 | + |
| 126 | +- `main.go`: Application entry point and error handling |
| 127 | +- `src/quebec/commands/main.go`: Command dispatch system |
| 128 | +- `src/juliett/sku/main.go`: Core object model |
| 129 | +- `src/mike/store/main.go`: Primary storage implementation |
| 130 | +- `src/november/local_working_copy/main.go`: Working copy management |
0 commit comments