docs: restructure README and create product documentation#273
Merged
Conversation
Rewrite README as a product-focused overview (~120 lines, down from 400). Move all crypto diagrams and technical deep-dives to docs/ARCHITECTURE.md. Create docs/DEVELOPMENT.md with local setup, testing, and workflow info. Delete outdated 00_START_HERE.md and clean up all references. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 4fc840844ff8
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughRestructures and consolidates documentation (adds Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client (Web / Desktop)
participant API as Backend API
participant IPFS as Kubo IPFS
participant IPNS as IPNS / Republish Scheduler
participant DB as Metadata DB
Client->>API: Upload encrypted file + metadata
API->>IPFS: ipfs add / pin via Kubo
IPFS-->>API: Return CID
API->>IPNS: Publish metadata pointer (IPNS record)
API->>DB: Persist metadata (CID, IPNS name, ownership, keys)
Note over IPNS,API: Background republish handled by scheduler with backoff
IPNS->>API: Republish ack / error
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ARCHITECTURE.md`:
- Line 23: Update the documentation text that reads "Same user + any auth method
→ same keypair → same vault" to explicitly state that keypair/vault unification
only occurs for auth methods that the user has explicitly linked, not across all
methods by default; replace or augment similar wording at the second occurrence
referencing "Same user + any auth method" (lines mentioning that behavior) with
a clear sentence that identities are independent across auth methods until the
user links them, and mention CipherBox's removal of implicit auth-method
auto-linking as the rationale for this behavior.
In `@docs/DEVELOPMENT.md`:
- Line 89: Update the desktop local-dev instructions to include setting
VITE_ENVIRONMENT=local in the desktop environment config alongside
VITE_API_URL=http://localhost:3000, and also ensure the Rust-side environment
variable CIPHERBOX_API_URL=http://localhost:3000 is documented so the native
backend and frontend use the same localhost API; mention the exact env keys
(VITE_API_URL, VITE_ENVIRONMENT, CIPHERBOX_API_URL) and where to add them
(desktop env file for VITE_*, Rust env for CIPHERBOX_*) so readers align
frontend and Rust backend to local.
In `@README.md`:
- Around line 22-27: The feature list currently presents items like "Sharing",
"Search", "Versioning", "Desktop (Linux/Windows)", "Sync" and "Recycle Bin" as
shipped; update README.md so MVP v1.0 only lists core shipped features (core
auth, encrypted file ops, web UI, macOS desktop, basic sync) and move or relabel
the bullets "Sharing", "Search", "Versioning", "Desktop — macOS, Windows, and
Linux via Tauri v2", and "Recycle Bin" as planned for v1.1+ (or relocate them
into a "Roadmap / Planned (v1.1+)" section), ensuring each moved item is
annotated with "Planned (v1.1+)" so readers can distinguish shipped vs planned
features.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: cc6f76f7-93a8-420d-bb10-f42ae5dc6295
📒 Files selected for processing (7)
.github/copilot-instructions.md.markdownlintignore.planning/codebase/STRUCTURE.md00_START_HERE.mdREADME.mddocs/ARCHITECTURE.mddocs/DEVELOPMENT.md
💤 Files with no reviewable changes (2)
- 00_START_HERE.md
- .markdownlintignore
Pinata was removed as IPFS provider in PR #171. Update all active documentation, planning files, and agent configs to reference Kubo (self-hosted IPFS) instead. Frozen specs and archived phase docs are left as-is since they are historical records. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 1f66ffcda647
- Clarify auth-method → keypair relationship requires same userId, not arbitrary auth methods (ARCHITECTURE.md) - Add VITE_ENVIRONMENT and CIPHERBOX_API_URL to desktop local-dev instructions (DEVELOPMENT.md) - Separate shipped vs planned features in README; move Sharing, Search, Versioning, Recycle Bin, and Windows/Linux desktop to Planned (v1.1+) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 232429127761
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.planning/codebase/ARCHITECTURE.md (1)
153-153:⚠️ Potential issue | 🟠 MajorCorrect backoff timing and clarify implementation location.
Line 153 states "TEE Republish: Exponential backoff (30s → 60s → 120s → 240s → 300s max)" but the codebase shows:
Location: The exponential backoff is implemented in the backend's republish scheduler (
apps/api/src/republish/republish.service.tslines 20–23, 353–354), not in the TEE worker. The TEE worker (tee-worker/src/routes/republish.ts) contains no retry or backoff logic.Max backoff value: The actual max is
3600s(1 hour), not300s(5 minutes). Constants:BASE_BACKOFF_SECONDS = 30,MAX_BACKOFF_SECONDS = 3600, formula:BASE_BACKOFF_SECONDS * 2^consecutiveFailurescapped at3600s.Revise to: "Backend Republish Scheduler: Exponential backoff for failed entries (30s → 60s → 120s → ... → 3600s max)."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.planning/codebase/ARCHITECTURE.md at line 153, Update the architecture doc line that incorrectly attributes exponential backoff to the TEE worker and misstated the max backoff: change the entry to "Backend Republish Scheduler: Exponential backoff for failed entries (30s → 60s → 120s → ... → 3600s max)" and note that the logic lives in apps/api/src/republish/republish.service.ts (not tee-worker/src/routes/republish.ts); ensure the description references the actual constants and formula used (BASE_BACKOFF_SECONDS = 30, MAX_BACKOFF_SECONDS = 3600, backoff = BASE_BACKOFF_SECONDS * 2^consecutiveFailures capped at MAX_BACKOFF_SECONDS).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In @.planning/codebase/ARCHITECTURE.md:
- Line 153: Update the architecture doc line that incorrectly attributes
exponential backoff to the TEE worker and misstated the max backoff: change the
entry to "Backend Republish Scheduler: Exponential backoff for failed entries
(30s → 60s → 120s → ... → 3600s max)" and note that the logic lives in
apps/api/src/republish/republish.service.ts (not
tee-worker/src/routes/republish.ts); ensure the description references the
actual constants and formula used (BASE_BACKOFF_SECONDS = 30,
MAX_BACKOFF_SECONDS = 3600, backoff = BASE_BACKOFF_SECONDS *
2^consecutiveFailures capped at MAX_BACKOFF_SECONDS).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e0979e9c-3dea-48e7-9849-bbbace5c844d
⛔ Files ignored due to path filters (1)
.claude/agents/security-reviewer.mdis excluded by!.claude/agents/**
📒 Files selected for processing (17)
.claude/claude.md.github/copilot-instructions.md.planning/ENVIRONMENTS.md.planning/MILESTONES.md.planning/PROJECT.md.planning/REFACTORING.md.planning/codebase/ARCHITECTURE.md.planning/codebase/CONCERNS.md.planning/codebase/INTEGRATIONS.md.planning/codebase/STACK.md.planning/codebase/TESTING.md.planning/research/PITFALLS.md.planning/research/STACK.md.planning/research/m3/ARCHITECTURE.md.planning/todos/pending/2026-02-14-bring-your-own-ipfs-node.mdREADME.mddocs/ARCHITECTURE.md
✅ Files skipped from review due to trivial changes (1)
- .planning/codebase/CONCERNS.md
🚧 Files skipped from review as they are similar to previous changes (2)
- README.md
- .github/copilot-instructions.md
Backoff logic is in the backend republish scheduler (republish.service.ts), not the TEE worker. Max backoff is 3600s, not 300s. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 67c51888f692
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.
You can also share your feedback on Copilot code review. Take the survey.
- Fix broken links in copilot-instructions.md (Preliminary/ → 00-Preliminary-R&D/) - Fix glob patterns in CONCERNS.md (escaped asterisks rendered as underscores) - Fix license label in STRUCTURE.md (Apache 2.0 → MIT) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: f113682b49f9
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/copilot-instructions.md (1)
154-159:⚠️ Potential issue | 🟠 MajorUpload example contradicts zero-knowledge guidance by allowing plaintext filename.
Line 157 (
fileName: file.name) conflicts with the document’s own “server never sees plaintext data” principle. The sample should send only encrypted payload/metadata fields.Suggested doc fix
- fileName: file.name, // plaintext OK for server audit + // No plaintext filename in transit; send encrypted metadata only🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/copilot-instructions.md around lines 154 - 159, The example currently sends plaintext filename via the api.post call (fileName: file.name) which violates the zero-knowledge rule; change the payload used in api.post('/vault/upload') so it does not include file.name directly—either remove the fileName field entirely or replace it with a privacy-preserving alternative (e.g., an encryptedFilename or filenameHash produced by the same client-side crypto routines that produced encryptedFile and fileIV), and ensure the server only receives encryptedFile, iv (bytesToHex(fileIV)), and the privacy-preserving filename field if present.
♻️ Duplicate comments (1)
README.md (1)
11-11:⚠️ Potential issue | 🟠 MajorClarify auth-method linking semantics for vault unification.
Line 11 implies vault unification across any login method by default. This should explicitly say vault sharing occurs when methods resolve to the same CipherBox identity (linked flow), not implicit cross-method matching.
Based on learnings: “CipherBox removes all auto-linking of auth methods by email... Users link methods explicitly via the Settings page; there is no cross-method email matching or findOrCreateUserByEmail logic.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 11, The README sentence implying automatic vault unification across login methods is misleading; update the copy where it says vaults are "the same user always gets the same vault" to explicitly state that vault sharing only happens when login methods are explicitly linked by the user via the Settings page and that CipherBox does not perform automatic cross-method linking (no email-based auto-linking or findOrCreateUserByEmail behavior). Replace the ambiguous phrase with language clarifying "linked flow" semantics and mention that unlinked auth methods remain separate until the user links them in Settings.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ARCHITECTURE.md`:
- Line 18: Update the documented IPNS republish cadence from "every 3h" to
"every 6h" wherever it appears (e.g., the line currently reading "TEE
(Phala/Nitro) ← IPNS Republish (every 3h)" and the repeated block around "IPNS
Republish" later in the file), and also clarify that the TEE (Phala/Nitro) is
only responsible for secure signing/decryption (not scheduling); ensure both
occurrences match the backend scheduler and use wording like "IPNS Republish
(every 6h) — TEE handles signing/decryption only."
In `@README.md`:
- Line 20: The README currently lists "Streaming AES-CTR" which conflicts with
our crypto standard; update the feature text to remove AES-CTR and state
AES-256-GCM for file and metadata encryption instead (e.g., replace "Streaming
AES-CTR for large files" with wording that uses AES-256-GCM and, if necessary,
mention chunked/streaming using AES-256-GCM with per-chunk nonces), and ensure
the README's crypto primitives list matches the project standard: AES-256-GCM,
ECIES secp256k1, ECDSA secp256k1, HKDF-SHA256, and Argon2.
---
Outside diff comments:
In @.github/copilot-instructions.md:
- Around line 154-159: The example currently sends plaintext filename via the
api.post call (fileName: file.name) which violates the zero-knowledge rule;
change the payload used in api.post('/vault/upload') so it does not include
file.name directly—either remove the fileName field entirely or replace it with
a privacy-preserving alternative (e.g., an encryptedFilename or filenameHash
produced by the same client-side crypto routines that produced encryptedFile and
fileIV), and ensure the server only receives encryptedFile, iv
(bytesToHex(fileIV)), and the privacy-preserving filename field if present.
---
Duplicate comments:
In `@README.md`:
- Line 11: The README sentence implying automatic vault unification across login
methods is misleading; update the copy where it says vaults are "the same user
always gets the same vault" to explicitly state that vault sharing only happens
when login methods are explicitly linked by the user via the Settings page and
that CipherBox does not perform automatic cross-method linking (no email-based
auto-linking or findOrCreateUserByEmail behavior). Replace the ambiguous phrase
with language clarifying "linked flow" semantics and mention that unlinked auth
methods remain separate until the user links them in Settings.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c1fb8a2c-056e-4211-9ceb-822b08824726
📒 Files selected for processing (7)
.github/copilot-instructions.md.planning/codebase/ARCHITECTURE.md.planning/codebase/CONCERNS.md.planning/codebase/STRUCTURE.mdREADME.mddocs/ARCHITECTURE.mddocs/DEVELOPMENT.md
✅ Files skipped from review due to trivial changes (1)
- .planning/codebase/CONCERNS.md
🚧 Files skipped from review as they are similar to previous changes (2)
- .planning/codebase/STRUCTURE.md
- .planning/codebase/ARCHITECTURE.md
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
.planning/codebase/TESTING.md:20
- This file states there is “no test framework installed” and “no test commands available”, but the repo now has
pnpm testat the root plus Jest in apps/api and Vitest in apps/web (with multiple*.spec.ts/*.test.tsfiles). Update this section (or clearly mark it as historical) so contributors aren’t misled about the current testing setup.
**Runner:**
- Not configured - no test framework installed
**Assertion Library:**
- Not configured
**Run Commands:**
```bash
# No test commands available
# package.json does not include test scripts
</details>
---
You can also share your feedback on Copilot code review. [Take the survey](https://www.surveymonkey.com/r/XP6L3XJ).
- Fix republish interval from 3h to 6h to match REPUBLISH_INTERVAL_HOURS=6 (ARCHITECTURE.md, README.md) - Update wallet key derivation diagram to SIWE→JWT→Web3Auth flow (ARCHITECTURE.md) - Clarify AES-256-CTR is for large media files, not all files (README.md) - Fix React version from 19 to 18 to match package.json (README.md) - Use fully-qualified @cipherbox/desktop filter for consistency (DEVELOPMENT.md) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: da48acf7845e
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.
Comments suppressed due to low confidence (1)
.planning/codebase/TESTING.md:20
- This doc claims there is “no test framework installed” and “package.json does not include test scripts”, but the current repo has Jest/Vitest/Playwright wired (
pnpm test,pnpm test:e2e, CI jobs, etc.). Since this file is being updated in this PR, it should either be refreshed to reflect the current testing setup or clearly labeled as a historical snapshot (and possibly moved under an archive folder) to avoid misleading contributors.
**Runner:**
- Not configured - no test framework installed
**Assertion Library:**
- Not configured
**Run Commands:**
```bash
# No test commands available
# package.json does not include test scripts
</details>
---
You can also share your feedback on Copilot code review. [Take the survey](https://www.surveymonkey.com/r/XP6L3XJ).
- Clarify plaintext vs ciphertext file sizes in ARCHITECTURE.md opening - Fix HKDF-SHA256 row: used for IPNS derivation, not wallet key derivation - Update INTEGRATIONS.md TEE status from "Planned" to "Implemented" - Fix STRUCTURE.md "Where to Add New Code" to use apps/ workspace paths - Update STRUCTURE.md implementation status table to reflect current state Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 844154f48456
Replace stale "no test framework" section with actual setup: Jest (API), Vitest (web, crypto), Playwright (E2E). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 46bef4f726cb
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 9 comments.
Comments suppressed due to low confidence (1)
.planning/codebase/INTEGRATIONS.md:27
- This section says Web3Auth is “Planned - Not Implemented”, but Web3Auth MPC Core Kit is already used in the web/desktop clients (e.g.
@web3auth/mpc-core-kitimports underapps/webandapps/desktop). Update this to reflect the current implementation status (and similarly for PostgreSQL/API if this doc is meant to be current).
**Web3Auth (Planned - Not Implemented):**
- Authentication and key derivation - User identity
- SDK/Client: `@web3auth/modal` (planned)
- Auth methods: Google, Apple, GitHub, Email, Magic Link, External Wallet
- JWKS endpoint: `https://api-auth.web3auth.io/jwks`
You can also share your feedback on Copilot code review. Take the survey.
- Fix copilot-instructions.md paths from Preliminary/ to 00-Preliminary-R&D/ - Update STACK.md project status from PoC-only to full implementation - Update STACK.md frameworks, runtime, package manager to current versions - Fix remaining Cypress/Puppeteer references in TESTING.md (framework reqs + CI) - Clarify E2E test prerequisites (infra services vs Playwright webServer) - Fix CI pipeline E2E description to not run on PRs by default - Fix todo file reference to non-existent kubo.provider.ts - Update DEVELOPMENT.md E2E section to reflect Playwright auto-start Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 066f4884ea72
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.planning/todos/pending/2026-02-14-bring-your-own-ipfs-node.md:
- Around line 8-9: Frontmatter contains a duplicated entry
"apps/api/src/ipfs/providers/local.provider.ts" (appears twice); remove the
duplicate so the path appears only once in the list and ensure the frontmatter
punctuation/formatting remains valid (no stray commas or blank lines) after
deletion.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: d9b123aa-59b9-430a-8269-ead01d5b2c52
📒 Files selected for processing (5)
.github/copilot-instructions.md.planning/codebase/STACK.md.planning/codebase/TESTING.md.planning/todos/pending/2026-02-14-bring-your-own-ipfs-node.mddocs/DEVELOPMENT.md
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.
Comments suppressed due to low confidence (2)
.planning/codebase/ARCHITECTURE.md:57
- This architecture overview still describes CipherBox as “Specification-First / Pre-Implementation” and labels the client/backend/TEE layers as “Specified, Not Implemented”. That contradicts the current repo layout (apps/web, apps/api, apps/desktop, tee-worker). Please update these layer descriptions to reflect the implemented components (or explicitly mark it as a historical snapshot) to prevent confusion.
**Overall:** Specification-First / Pre-Implementation Technology Demonstrator
**Key Characteristics:**
- Complete specification documents define the target architecture before implementation
- Single proof-of-concept (PoC) console harness validates core IPFS/IPNS and encryption flows
- Layered E2E encryption with zero-knowledge server design
- Client-side cryptographic operations with server acting as relay and storage proxy
- Per-folder IPNS records enabling future modular sharing capabilities
## Layers
**Specification Layer:**
- Purpose: Define complete system design, security model, and implementation contract
- Location: `00-Preliminary-R&D/Documentation/`
- Contains: PRD, technical architecture, API spec, data flows, client spec, implementation roadmap
- Depends on: None (foundation documents)
- Used by: All implementation code (when built)
**Proof-of-Concept Layer:**
- Purpose: Validate IPFS/IPNS assumptions and encryption flows end-to-end
- Location: `00-Preliminary-R&D/poc/`
- Contains: Single-file console harness demonstrating file/folder operations
- Depends on: IPFS daemon, cryptographic libraries
- Used by: Architecture validation only (not production)
**Client Layer (Specified, Not Implemented):**
- Purpose: Handle all encryption/decryption, key management, UI
- Location: (Not yet created - see `00-Preliminary-R&D/Documentation/CLIENT_SPECIFICATION.md`)
- Contains: React 18 web app, Tauri/Electron desktop app with FUSE
- Depends on: Web3Auth SDK, Web Crypto API, CipherBox Backend API
- Used by: End users
**Backend Layer (Specified, Not Implemented):**
- Purpose: Token management, IPFS/IPNS relay, vault metadata storage, TEE coordination
- Location: (Not yet created - see `00-Preliminary-R&D/Documentation/API_SPECIFICATION.md`)
- Contains: NestJS API with 15 endpoints
- Depends on: PostgreSQL, IPFS (Kubo), Web3Auth JWKS, TEE providers
- Used by: Client applications
**TEE Layer (Specified, Not Implemented):**
- Purpose: Automatic IPNS republishing without user devices online
- Location: External services (Phala Cloud primary, AWS Nitro fallback)
- Contains: Secure enclaves for IPNS key decryption and signing
- Depends on: Backend republish schedule
- Used by: Backend cron jobs
.planning/codebase/STACK.md:84
- The stack doc claims “TypeScript 5.7+” and lists
@web3auth/modalunder “Planned Production”, but the workspace uses TypeScript^5.9.3and the web app depends on@web3auth/mpc-core-kit/@web3auth/ethereum-mpc-provider(seeapps/web/package.json). Please update these entries so the stack overview matches actual dependencies.
**Primary:**
- TypeScript 5.7+ - All application code (web, desktop, backend, crypto, PoC)
**Secondary:**
- JavaScript (ES2022) - Compilation target
- SQL - PostgreSQL database schema and migrations
- Rust - TEE worker (Phala Cloud) and desktop FUSE filesystem
## Runtime
**Environment:**
- Node.js 20+ - Backend API and build tooling
- Browser (Chrome/Firefox/Safari) - Web app
- Tauri v2 - Desktop app (macOS)
**Package Manager:**
- pnpm 9+ - Workspace-based monorepo management
- Lockfile: `pnpm-lock.yaml` at workspace root
## Frameworks
**Web App:**
- React 18 - Frontend framework
- Tailwind CSS - Styling
- Vite - Build tooling
**Backend:**
- NestJS - Backend framework (Node.js)
- TypeORM - Database ORM
- BullMQ + Redis - Job queue
**Desktop:**
- Tauri v2 - Desktop shell
- FUSE-T (SMB backend) - Virtual filesystem mount (macOS)
**Build/Dev:**
- TypeScript 5.7+ - Type checking and compilation
- ESLint 9 - Linting
- Vitest - Unit testing (web, crypto)
- Jest - Unit testing (API)
- Playwright - E2E testing
## Key Dependencies
**PoC Critical (from `00-Preliminary-R&D/poc/package.json`):**
- `ipfs-http-client` 60.0.1 - IPFS node communication
- `eciesjs` 0.4.7 - ECIES encryption (secp256k1)
- `@noble/secp256k1` 2.1.0 - Public key derivation
- `dotenv` 16.4.5 - Environment configuration
**PoC Dev Dependencies:**
- `@types/node` 20.19.30 - Node.js type definitions
- `typescript` 5.4.2 - TypeScript compiler
- `tsx` 4.7.1 - TypeScript execution
- `eslint` 8.57.0 - Linting
**Planned Production:**
- `@web3auth/modal` - Auth and key derivation
- `jose` - JWT verification (backend)
- PostgreSQL client - Database access (backend)
- `winston` - Structured logging framework (backend)
- `nest-winston` - NestJS Winston integration (backend)
- Datadog/Splunk transport - Log aggregation for dev/prod environments
You can also share your feedback on Copilot code review. Take the survey.
- Remove duplicate local.provider.ts entry in todo frontmatter - Fix </role> tag indentation in security-reviewer agent - Fix key hierarchy: Root Folder Key is random, not derived - Update CONCERNS.md: replace "no production implementation" with legacy PoC note - Fix copilot-instructions.md version 1.10.0 → 1.11.1 - Remove plaintext fileName from upload example (zero-knowledge violation) - Update INTEGRATIONS.md: Web3Auth is implemented, not planned Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 9ece75b9d3cc
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/copilot-instructions.md:
- Around line 317-325: The listing in .github/copilot-instructions.md references
a non-existent document
"00-Preliminary-R&D/Documentation/IMPLEMENTATION_ROADMAP.md"; update the
reference by either removing that bullet or replacing it with the correct
existing document path/name (e.g., the actual roadmap filename) and ensure the
linked filename exactly matches the repository (check spelling/casing), so the
entry in the list (the bullet containing IMPLEMENTATION_ROADMAP.md) points to a
real file or is removed.
- Around line 30-37: Update the documentation table in
.github/copilot-instructions.md to remove or correct the non-existent entry
IMPLEMENTATION_ROADMAP.md: either delete the row referencing
IMPLEMENTATION_ROADMAP.md from the table or replace it with the correct
filename/path if an implementation roadmap exists elsewhere in the repo (search
for "IMPLEMENTATION_ROADMAP" or similar to locate the correct file and update
the table entry accordingly).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b12d80c5-758f-4465-840b-ee4adde7b5ab
⛔ Files ignored due to path filters (1)
.claude/agents/security-reviewer.mdis excluded by!.claude/agents/**
📒 Files selected for processing (4)
.github/copilot-instructions.md.planning/codebase/CONCERNS.md.planning/codebase/INTEGRATIONS.md.planning/todos/pending/2026-02-14-bring-your-own-ipfs-node.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .planning/todos/pending/2026-02-14-bring-your-own-ipfs-node.md
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.
You can also share your feedback on Copilot code review. Take the survey.
- Remove broken IMPLEMENTATION_ROADMAP.md references (file doesn't exist) - Fix upload example: POST /vault/upload → POST /ipfs/upload with FormData - Rename diagram label ipnsName → fileMetaIpnsName for v2 FilePointer - Update CONCERNS.md: tests exist, coverage below targets (not zero tests) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: b2cb460a212b
…implementation Remove all references to 00-Preliminary-R&D/ frozen specs. Replace with references to docs/ (ARCHITECTURE.md, DEVELOPMENT.md, etc.) and actual codebase paths (apps/api, apps/web, packages/crypto, tee-worker). Update: API endpoints, tech stack, key hierarchy, upload flow, encryption primitives, testing commands, and development patterns to match current implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: d0c75ea13cb5
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.
You can also share your feedback on Copilot code review. Take the survey.
Remove PoC-centric concerns, add production-relevant issues: orphaned IPNS records, silenced unpin failures, large monolithic files, FUSE-T/WinFSP fragility, actual test coverage gaps. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: ad9f15bae3ec
- ARCHITECTURE.md: Remove "Pre-Implementation" framing, document all implemented layers, fix upload endpoint to POST /ipfs/upload, add v2 FilePointer schema references - INTEGRATIONS.md: Remove "Planned"/"PoC" labels for implemented integrations, add actual file paths, staging deployment details - STACK.md: Fix @web3auth/modal to @web3auth/mpc-core-kit, Ed25519 via @noble/ed25519 not libsodium.js, pnpm not npm/yarn Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: ddfb7d5831da
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/copilot-instructions.md:
- Around line 82-89: Remove the AES-256-CTR row from the algorithm table and
update the non-negotiable primitive list to only include AES-256-GCM, ECIES
secp256k1, ECDSA secp256k1 (replace Ed25519 reference if present), HKDF-SHA256,
and Argon2; ensure the table entries and any adjacent guidance text no longer
mention AES-256-CTR and instead list the approved primitives (AES-256-GCM, ECIES
secp256k1, ECDSA secp256k1, HKDF-SHA256, Argon2) so agents follow the repo’s
approved cipher set.
- Line 34: Update the sentence about the Phase 1 ECDSA keypair so it clarifies
that different auth methods (Google/email/wallet) do not automatically share or
converge on the same Phase 1 keypair; explicitly state that each auth method
represents an independent identity unless the user explicitly links accounts via
Settings. Replace or augment the existing line referencing "Phase 1 keypair" and
"CipherBox `userId`" to note that only explicit user-initiated linking creates a
shared identity, and remove any implication of automatic account merging.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 3e76f387-d822-42ef-adcd-1cec2ad54c91
📒 Files selected for processing (3)
.github/copilot-instructions.md.planning/codebase/CONCERNS.mddocs/ARCHITECTURE.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/ARCHITECTURE.md
Make explicit that identity convergence is backend-controlled, not automatic across auth methods. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 5b14ac186038
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.planning/codebase/ARCHITECTURE.md:
- Line 57: Update the TEE cron schedule text to match the actual republish
interval by replacing the line "Used by: Backend cron jobs (every 3 hours)" with
"Used by: Backend cron jobs (every 6 hours)" (or otherwise align the description
to the 6-hour republish interval referenced in INTEGRATIONS.md); locate the
exact string "Used by: Backend cron jobs (every 3 hours)" in ARCHITECTURE.md and
adjust it so the documented schedule matches the implemented 6-hour interval.
In @.planning/codebase/INTEGRATIONS.md:
- Line 50: Update the documentation entry that says "Every 3 hours" to "Every 6
hours" so it matches the actual republish interval; verify against the
REPUBLISH_INTERVAL_HOURS constant used by the republish service
(REPUBLISH_INTERVAL_HOURS = 6) and ensure the INTEGRATIONS.md schedule text
reflects the 6-hour interval.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0e5d3c71-ce1d-422b-bff2-7891164e0889
📒 Files selected for processing (3)
.planning/codebase/ARCHITECTURE.md.planning/codebase/INTEGRATIONS.md.planning/codebase/STACK.md
The actual interval is REPUBLISH_INTERVAL_HOURS = 6 in apps/api/src/republish/republish.service.ts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 6164db275302
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.
You can also share your feedback on Copilot code review. Take the survey.
- Align INTEGRATIONS.md env var names with actual .env.example - Fix DEVELOPMENT.md unit test command to exclude E2E workspace - Update copilot-instructions.md IPNS key hierarchy to reflect random per-file keys - Move Sharing and Recycle Bin from Planned to current features in README Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Entire-Checkpoint: 389fb7b6a122
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
README.mdas a product-focused overview (~120 lines, down from ~400) with features list, simplified architecture diagram, updated tech stack, and getting started sectiondocs/ARCHITECTURE.md— all crypto diagrams, key derivation flows, encryption hierarchy, threat model, and design decisions moved verbatim from the old READMEdocs/DEVELOPMENT.md— local setup guide covering Docker, environment config, running web/desktop, testing, API client generation, and code quality00_START_HERE.md— outdated pre-implementation artifact (referenced 3-person team, 12-week timeline, listed shipped features as deferred).markdownlintignore,.github/copilot-instructions.md,.planning/codebase/STRUCTURE.md; fixed pre-existing markdownlint errors in touched filesTest plan
pnpm lint:mdpasses on all new/modified files00_START_HERE.mdin the repo (grepconfirms zero matches)docs/ARCHITECTURE.md,docs/DEVELOPMENT.md, etc.)docs/ARCHITECTURE.mdpreserved exactly from original README🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Storage
Authentication
Testing
Chores