Skip to content

Commit e80b984

Browse files
ErcinDedeogluErcinDedeoglu
committed
feat(docs): update README and add architecture documentation
1 parent 9d04e92 commit e80b984

2 files changed

Lines changed: 163 additions & 55 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -183,8 +183,6 @@ The plugin uses **activity-aware batching** to prevent excessive syncs during he
183183

184184
During heavy activity, syncs are batched and fire at most every 30 seconds.
185185

186-
See [docs/SYNC.md](docs/SYNC.md) for detailed architecture documentation.
187-
188186
## Security
189187

190188
- Credentials are encrypted with AES-256-GCM before upload
@@ -193,60 +191,16 @@ See [docs/SYNC.md](docs/SYNC.md) for detailed architecture documentation.
193191
- Token is stored locally, never uploaded
194192
- Atomic commits with compare-and-swap prevent race conditions
195193

196-
## Architecture
194+
## Documentation
197195

198-
```
199-
src/
200-
├── index.ts # Main entry point (re-exports from plugin)
201-
├── plugin/ # Plugin module
202-
│ ├── plugin.ts # Plugin definition and hooks
203-
│ ├── state-manager.ts # Plugin state management
204-
│ ├── sync-handler.ts # Sync operation handler
205-
│ └── types.ts # Plugin types
206-
├── storage/ # Storage backend abstraction
207-
│ ├── interface.ts # StorageBackend interface
208-
│ ├── repo/ # GitHub Repo backend
209-
│ │ ├── repo-client.ts # API client
210-
│ │ ├── fetch.ts # Fetch with retry logic
211-
│ │ └── errors.ts # API error types
212-
│ └── index.ts # Exports
213-
├── sync/
214-
│ ├── engine/ # Sync engine module
215-
│ │ ├── sync-engine.ts # Core orchestration
216-
│ │ ├── state.ts # Local state management
217-
│ │ ├── manifest.ts # Manifest operations
218-
│ │ ├── result.ts # Result builders
219-
│ │ └── errors.ts # Sync error types
220-
│ ├── operations/ # Push/pull/merge operations
221-
│ │ ├── push.ts # Push to remote
222-
│ │ ├── pull.ts # Pull from remote
223-
│ │ ├── merge-operation.ts # Merge conflicts
224-
│ │ └── helpers.ts # Encryption helpers
225-
│ ├── merge/ # Three-way merge module
226-
│ │ ├── json-merge.ts # JSON merge algorithm
227-
│ │ ├── jsonl-merge.ts # JSONL merge algorithm
228-
│ │ └── utils.ts # Merge utilities
229-
│ ├── watcher/ # File watcher module
230-
│ │ ├── file-watcher.ts # Main watcher class
231-
│ │ ├── directory-watcher.ts # Directory watching
232-
│ │ └── ignore-patterns.ts # File ignore rules
233-
│ ├── vector-clock.ts # Vector clock operations
234-
│ └── packer.ts # Compression/chunking
235-
├── crypto/
236-
│ └── encrypt.ts # AES-256-GCM encryption
237-
├── data/ # Data loading module
238-
│ ├── category-loader.ts # Load by category
239-
│ ├── directory-loader.ts # Directory traversal
240-
│ ├── parsers.ts # JSON/JSONL parsing
241-
│ ├── writer.ts # Write local data
242-
│ └── state.ts # Config/state persistence
243-
└── types/ # TypeScript definitions
244-
├── config.ts # Config types
245-
├── manifest.ts # Manifest types
246-
├── sync.ts # Sync result types
247-
├── vector-clock.ts # Vector clock types
248-
└── paths.ts # Path configuration
249-
```
196+
| Guide | Description |
197+
|-------|-------------|
198+
| [Architecture](docs/ARCHITECTURE.md) | Code structure and modules |
199+
| [Sync Architecture](docs/SYNC.md) | Sync triggers, batching, data categories |
200+
| [Sync Paths](docs/SYNC-PATHS.md) | OpenCode file locations by platform |
201+
| [Development Setup](docs/DEV-SETUP.md) | Local development environment |
202+
| [Publishing](docs/PUBLISH.md) | npm release process |
203+
| [LLM Installation](docs/LLM-INSTALL.md) | Instructions for AI coding agents |
250204

251205
## Development
252206

‎docs/ARCHITECTURE.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Architecture
2+
3+
## Directory Structure
4+
5+
```
6+
src/
7+
├── index.ts # Main entry point
8+
├── plugin/ # Plugin module
9+
├── storage/ # Storage backend abstraction
10+
├── sync/ # Sync engine and operations
11+
├── crypto/ # Encryption utilities
12+
├── data/ # Data loading module
13+
└── types/ # TypeScript definitions
14+
```
15+
16+
## Modules
17+
18+
### plugin/
19+
20+
OpenCode plugin integration.
21+
22+
| File | Purpose |
23+
|------|---------|
24+
| `plugin.ts` | Plugin definition and hooks |
25+
| `state-manager.ts` | Plugin state management |
26+
| `sync-handler.ts` | Sync operation handler |
27+
| `types.ts` | Plugin types |
28+
29+
### storage/
30+
31+
Storage backend abstraction for GitHub repository.
32+
33+
| File | Purpose |
34+
|------|---------|
35+
| `interface.ts` | StorageBackend interface |
36+
| `repo/repo-client.ts` | GitHub API client |
37+
| `repo/fetch.ts` | Fetch with retry logic |
38+
| `repo/errors.ts` | API error types |
39+
40+
### sync/engine/
41+
42+
Core sync orchestration.
43+
44+
| File | Purpose |
45+
|------|---------|
46+
| `sync-engine.ts` | Main sync orchestration |
47+
| `state.ts` | Local state management |
48+
| `manifest.ts` | Manifest operations |
49+
| `result.ts` | Result builders |
50+
| `helpers.ts` | Engine utilities |
51+
| `retry.ts` | Retry logic |
52+
| `errors.ts` | Sync error types |
53+
| `types.ts` | Engine types |
54+
55+
### sync/operations/
56+
57+
Push, pull, and merge operations.
58+
59+
| File | Purpose |
60+
|------|---------|
61+
| `push.ts` | Push to remote |
62+
| `pull.ts` | Pull from remote |
63+
| `merge-operation.ts` | Merge conflicts |
64+
| `sharding.ts` | Item sharding |
65+
| `helpers.ts` | Operation utilities |
66+
| `crypto-helpers.ts` | Encryption helpers |
67+
| `types.ts` | Operation types |
68+
69+
### sync/merge/
70+
71+
Three-way merge algorithms.
72+
73+
| File | Purpose |
74+
|------|---------|
75+
| `json-merge.ts` | JSON merge algorithm |
76+
| `jsonl-merge.ts` | JSONL merge algorithm |
77+
| `utils.ts` | Merge utilities |
78+
| `types.ts` | Merge types |
79+
80+
### sync/watcher/
81+
82+
File system watcher for auto-sync.
83+
84+
| File | Purpose |
85+
|------|---------|
86+
| `file-watcher.ts` | Main watcher class |
87+
| `directory-watcher.ts` | Directory watching |
88+
| `ignore-patterns.ts` | File ignore rules |
89+
| `types.ts` | Watcher types |
90+
91+
### sync/ (root files)
92+
93+
| File | Purpose |
94+
|------|---------|
95+
| `vector-clock.ts` | Vector clock operations |
96+
| `packer.ts` | Blob compression |
97+
| `item-packer.ts` | Per-item compression |
98+
| `tombstone.ts` | Deletion tracking |
99+
| `local-lock.ts` | Local sync locking |
100+
101+
### crypto/
102+
103+
| File | Purpose |
104+
|------|---------|
105+
| `encrypt.ts` | AES-256-GCM encryption |
106+
107+
### data/
108+
109+
Local data loading and persistence.
110+
111+
| File | Purpose |
112+
|------|---------|
113+
| `category-loader.ts` | Load by category |
114+
| `directory-loader.ts` | Directory traversal |
115+
| `parsers.ts` | JSON/JSONL parsing |
116+
| `writer.ts` | Write local data |
117+
| `state.ts` | Config/state persistence |
118+
119+
### types/
120+
121+
TypeScript type definitions.
122+
123+
| File | Purpose |
124+
|------|---------|
125+
| `config.ts` | Config types |
126+
| `manifest.ts` | Manifest types |
127+
| `sync.ts` | Sync result types |
128+
| `vector-clock.ts` | Vector clock types |
129+
| `categories.ts` | Category definitions |
130+
| `paths.ts` | Path configuration |
131+
132+
## Data Flow
133+
134+
```
135+
Local Files → Data Loader → Sync Engine → Storage Backend → GitHub Repo
136+
↑
137+
Vector Clock
138+
Merge Logic
139+
Encryption
140+
```
141+
142+
## Key Concepts
143+
144+
### Vector Clocks
145+
Track causality between machines. See `sync/vector-clock.ts`.
146+
147+
### Three-Way Merge
148+
Resolve conflicts using common ancestor. See `sync/merge/`.
149+
150+
### Tombstones
151+
Track deletions for propagation. See `sync/tombstone.ts`.
152+
153+
### Sharding
154+
Split large item collections across files. See `sync/operations/sharding.ts`.

0 commit comments

Comments
 (0)