docs: rewrite CLAUDE.md with focused architecture guidance

[Cybersoulja]

$(cat <<'EOF'

Summary

• Replaces verbose file/component listings with explanations of how packages connect (dev proxy, build pipeline, Assets binding)
• Documents non-obvious behavior: base64 key encoding (ROOT_FOLDER = "IA=="), request lifecycle, why catch-all routes must be registered last, share link storage in R2
• Adds missing commands: running a single worker test file, launching the worker dev server locally
• Removes easily-discoverable file lists (test files, component directories) and generic advice sections

Test plan

• Review CLAUDE.md for accuracy against the codebase
• Verify all commands listed are correct

https://claude.ai/code/session_01RKoDzdZwpYz1AYzgcnV3Ts
EOF
)

---

Generated by Claude Code

Summary by Sourcery

Rewrite CLAUDE.md to focus on architecture, data flow, and development workflows instead of file listings and low-level implementation details.

Documentation:

• Document how worker, dashboard, and Cloudflare Workers Assets binding integrate, including dev proxying and build-time asset bundling.
• Explain worker request lifecycle, middleware ordering requirements, and base64-encoded object key handling (including ROOT_FOLDER).
• Clarify share link storage in R2, public access behavior, and dashboard authentication and boot flow.
• Describe how to add new API endpoints, including validation, routing, and testing expectations.
• Condense and reorganize testing and code style guidance to highlight the main commands, tools, and conventions.

[gitnotebooks]

Review these changes at https://app.gitnotebooks.com/Cybersoulja/R2-Explorer/pull/5

[sourcery-ai]

Reviewer's Guide

Rewrites CLAUDE.md to focus on architecture, request lifecycle, dev/prod wiring between worker and dashboard, and practical commands, while removing verbose file/route listings and generic advice.

Sequence diagram for worker request lifecycle and share links

sequenceDiagram
  participant U as User
  participant D as Dashboard_SPA
  participant W as Worker_R2Explorer
  participant RO as ReadOnly_middleware
  participant AUTH as Auth_middleware
  participant H as GetObject_handler
  participant S as GetShareLink_handler
  participant R2 as R2_bucket

  U->>D: Navigate to folder
  D->>W: GET /api/buckets/:bucket/:key
  W->>RO: apply readonly middleware
  RO-->>W: allow (GET/HEAD)
  W->>AUTH: basicAuth or cloudflareAccess
  AUTH-->>W: set authentication_username
  W->>H: GetObject.handle
  H->>R2: get object by base64 key
  R2-->>H: object data
  H-->>D: file listing/contents

  U->>W: GET /share/:shareId
  W->>S: GetShareLink.handle
  S->>R2: get .r2-explorer/sharable-links/:shareId.json
  R2-->>S: share metadata
  S-->>U: public file response

Loading

File-Level Changes

Change	Details	Files
Refocus commands and workflow guidance toward realistic dev, test, and release usage.	Condenses command list under a single Commands section with clearer descriptions. Documents how to run only worker integration tests and a single Vitest file. Clarifies Playwright E2E behavior and dashboard/worker dev server commands. Simplifies release/changeset guidance and ties it into Git workflow expectations.	CLAUDE.md
Document how worker, dashboard, and dev proxy architecture fit together.	Explain that the worker is the published npm package serving both API and SPA via ASSETS binding and Chanfana-based routes. Describe the dashboard build artifact flow into the worker during pnpm build-worker and the lack of a separate frontend server in production. Describe local dev wiring where the dashboard dev server proxies /api/* to a locally running wrangler dev instance. Summarize worker middleware chain (CORS, readonly, auth, routes) and request lifecycle at a high level.	CLAUDE.md
Clarify non-obvious backend behaviors: key encoding, route registration order, and share link storage.	Document that object keys in API routes are base64-encoded, with ROOT_FOLDER represented as "IA==" and decoded via atob helpers. Call out that catch-all object routes must be registered last to avoid shadowing more specific endpoints. Describe where share-link metadata is stored in R2, how the public /share/:shareId route bypasses auth, and that passwords are SHA-256 hashed.	CLAUDE.md
Provide concise patterns for adding new API endpoints and integrating them with tests and dashboard.	Compress the multi-step "Adding a new API endpoint" section into a tighter, implementation-focused checklist. Emphasize using OpenAPIRoute + Zod schemas, accessing buckets through c.env, and registering routes before catch-all handlers. Remind authors to add worker integration tests and dashboard appUtils.js calls for new endpoints.	CLAUDE.md
Streamline and declutter documentation by removing long file listings and generic sections while retaining key style and testing details.	Remove exhaustive repository structure, route tables, component lists, and "Important files" tables in favor of higher-level architecture descriptions. Trim generic code style, security, debugging, and resource sections down to the most actionable rules (Biome usage, indentation, quotes, key disabled rules). Summarize testing sections so they focus on frameworks, locations, and helper utilities rather than enumerating every test file.	CLAUDE.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[gemini-code-assist]

Code Review

This pull request refactors CLAUDE.md to provide more concise and structured guidance for Claude Code, including updated command references, a new architecture overview, and refined instructions for adding API endpoints. The review feedback suggests clarifying the route registration order to prevent shadowing and emphasizing the need to validate R2 bucket bindings when accessing them via environment variables.

[gemini-code-assist]

The instruction that catch-all routes must be registered 'last' is slightly ambiguous. In packages/worker/src/index.ts, some routes (like /api/emails/send) are registered after them. It's more accurate to say they must be registered after more specific routes that share the same path prefix to avoid shadowing.

Suggested change

	- **Routes**: each endpoint is a class extending `OpenAPIRoute` from Chanfana, one file per endpoint under `src/modules/`. Route registration order matters — the catch-all object routes (`GET /api/buckets/:bucket/:key`, `POST /api/buckets/:bucket/:key`) must be registered last.
	- **Routes**: each endpoint is a class extending `OpenAPIRoute` from Chanfana, one file per endpoint under `src/modules/`. Route registration order matters — specific routes under a prefix (e.g., `/api/buckets/:bucket/shares`) must be registered before catch-all routes (e.g., `/api/buckets/:bucket/:key`).

[gemini-code-assist]

When accessing the R2 bucket via c.env[bucketName], it is important to validate that bucketName corresponds to an actual R2 bucket binding and not another environment variable or internal binding (like ASSETS). Blindly indexing c.env with a user-provided string from the URL can lead to runtime errors or unintended access to other bindings.

Suggested change

	4. Access the R2 bucket via `c.env[bucketName]` — throw `HTTPException(500)` if missing.
	4. Access the R2 bucket via `c.env[bucketName]` — validate it is a valid R2 bucket and throw `HTTPException(500)` if missing or invalid.