From 6d285433c04b4c8b097ca316fd5a683c62109322 Mon Sep 17 00:00:00 2001 From: Jason Tame Date: Sat, 4 Oct 2025 09:38:33 +0200 Subject: [PATCH 01/10] fix(docs): update database url on overview page --- docs/src/content/docs/core/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/core/overview.mdx b/docs/src/content/docs/core/overview.mdx index b954edfcc..67894b6f7 100644 --- a/docs/src/content/docs/core/overview.mdx +++ b/docs/src/content/docs/core/overview.mdx @@ -16,7 +16,7 @@ _Peter Pistorius gives a 5 minute tour of RedwoodSDK._ 1. [Request Handling, Routing & Responses](/core/routing) 1. [React Server Components](/core/react-server-components) -1. [Database](/core/database) +1. [Database](/core/database-do) 1. [Storage](/core/storage) 1. [Realtime](/core/realtime) 1. [Queues & Background Jobs](/core/queues) From 3b81cbfe4f3972b3c83efe9966692a7d3f7a7793 Mon Sep 17 00:00:00 2001 From: justinvdm Date: Mon, 6 Oct 2025 04:36:17 +0200 Subject: [PATCH 02/10] Revert no longer relevant doc transform mentions in arch docs --- .cursor/rules/user/justin.mdc | 121 ------------------------ docs/architecture/documentTransforms.md | 19 ++-- 2 files changed, 9 insertions(+), 131 deletions(-) delete mode 100644 .cursor/rules/user/justin.mdc diff --git a/.cursor/rules/user/justin.mdc b/.cursor/rules/user/justin.mdc deleted file mode 100644 index 8836b9299..000000000 --- a/.cursor/rules/user/justin.mdc +++ /dev/null @@ -1,121 +0,0 @@ ---- -alwaysApply: true ---- - -* Work Log Protocol: All development must start by creating/updating a work log in directory `/.notes/justin/worklogs/` directory, with the file name format `YYYY-MM-DD-description.md`. The initial log must define the problem, plan, and context. The log must be updated in real-time throughout the development process (types, tests, implementation) with all notable events: decisions and their rationale, blockers, discoveries, and plan changes. It is a continuous journal. -* Work logs should be written as if by me, appending for each new task, finding, decision, etc. If I ask you to correct a mistake of your own, do not add content on that change in the work log, but instead revise as if that mistake never happened - think of what I would have done in the first place. -* Never say "Final" or "Definitive" or similar. Everything is an attempt, and subject to the test of time. -* Avoid "fluff" at the end of a section intended to round it off. Example (avoid this!): "This approach, combining a high-level stitching strategy with low-level, well-tested extraction utilities, ensures the solution is not only architecturally sound but also maintainable and correct." -* Architecture Revision Protocol: Architecture documents in `/docs/architecture` are to be revised only as the final step, after implementation is stable and tests pass. Use the completed work log as the primary source to distill the final, successful implementation's "why" into the formal documentation, following the established problem/solution narrative format. -* The user prefers technical writing to maintain consistent tone, style, and formatting; use high-level explanations; and avoid references to programming symbols. [[memory:8001383]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001380]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001377]] -* The user prefers a neutral writing tone, including in PR descriptions, avoiding dramatic or hyperbolic language. They avoid specific words that add undue emphasis or urgency, such as “killing,” “unreliable,” “risk,” “obscured,” and “critically.” [[memory:8001374]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:8001371]] -* The user prefers that the assistant adopt a less formal, more human, and casual tone in messages, avoiding stiffness and passive-aggressive phrasing. They also prefer concise, short communications using bullet points and bold keywords, avoiding long-winded explanations, overly dramatic language, and words like “essential” or “critical.” [[memory:6170010]] -* The user prefers that the assistant avoid using the word 'new' in documentation, as it is not important and will quickly become outdated. [[memory:6165420]] -* The user prefers that when modifying documentation, the assistant include all original context and not drop any details. [[memory:4798121]] -* Project uses the debug library for long-term logging with minimal verbosity, logging only failures. [[memory:4586459]] -* The user prefers tentative, exploratory language (“it seems,” “I think,” “might be”) over assertive claims to encourage openness and humility. They always avoid dramatic language and specific words like “killing” and “unreliable.” [[memory:4586455]] -* The user prefers documentation to avoid promotional or selling language and not claim that the architecture is superior. [[memory:4586453]] -* The user prefers using 'rwsdk' as the prefix instead of 'rws' throughout the codebase. [[memory:4586450]] -* When importing from `.mts` source files, use the `.mjs` extension in the import path. TypeScript handles the resolution, so even though the files have a `.mts` extension, the import specifiers must use `.mjs` . [[memory:4544197]] -* Prefer dependency injection over mocking in tests. Dependency injection makes a function's dependencies explicit and allows for passing in controlled versions for testing. Mocking can hide dependencies, lead to leaky state between tests, and make tests more brittle. [[memory:4223216]] -* Architecture documentation should focus on the "why" behind a design decision. It must explain the problem, the constraints considered, and the rationale for the chosen solution. The narrative is as important as the technical description. [[memory:4132497]] -* Architecture documentation should be clear, easy to understand, and avoid unnecessary technical jargon or low-level implementation details like specific function or variable names. The goal is to explain the system's design, not its line-by-line implementation. [[memory:4132491]] -* When making significant changes to the framework's architecture—including adding, modifying, or removing core functionalities—a corresponding entry must be created or updated in the `docs/architecture` directory. [[memory:4132489]] -* The user prefers that the assistant not hardcode values and avoid hardcoded paths or constants. [[memory:4059607]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:3430114]] -* Pipe all your commands through `cat` when possible, ensuring to pipe stderr and stdout, so that we can avoid interactivity on my side being a blocker as much as possible -* If asked to use git worktrees to work on a task, use ~/rw/worktrees// as the dir name -* NEVER use the word "final" -* Everything is an attempt, and subject to the test of time -* For any non-trivial task involving investigation or multiple attempts, create or update a work log to tell the story of the problem-solving journey. Frame the log as a narrative of each attempt, explaining the rationale and the findings that led to the next step, and conclude with the currently accepted solution. Store all work logs in a .worklogs/justin directory at the project root, using the filename format YYYY-MM-DD-short-description.md. -* Don't add comments unless I ask. -* Do this: - -if (foo) { - bar -} - -Do not do this - -if (foo) bar -* All changes that are larger scale, architecturally relevant or affect the behaviour of the system, start with architecture documentation (in docs/architecture/). If there's no relevant doc, create one anew. First make sure the change to be made is documented here correctly. When complete, come up with a list of the tasks to be done to refacor the code to make the necessary changes. Then stop and wait for my approval before proceeding with the corresponding code changes. -* Use ' isntead of ’ -* Use - instead of — -* Style Guide: Plain Technical Communication - - When generating any text (PR descriptions, documentation, code comments, etc.), adhere strictly to the following rules: - - 1. Use Simple, Direct Language: Write for clarity. Avoid jargon and complex vocabulary where a simpler word will do. - 2. Describe Actions, Not Intent: Instead of explaining the purpose or goal of a piece of code (e.g., "to verify integrity"), describe the literal action it performs (e.g., "compares file checksums"). - 3. No Subjective Qualifiers: Do not use adjectives that evaluate quality or value (e.g., good, robust, easy, safe, comprehensive). Stick to objective facts. - 4. Avoid Abstract Concepts: Break down high-level technical concepts into their concrete, constituent steps. For example, instead of "automated verification," state the specific checks that are run: "runs a checksum comparison and smoke tests." - 5. Be Concise: Omit unnecessary words. -* When generating a PR description or similar documentation, structure the text to first explain the problem or the previous state. Then, introduce the solution and describe its key functional outcomes at a high level. Avoid low-level implementation details unless they are essential to understanding the core change. Conclude with the testing status and what still needs to be validated. Maintain a direct and technical tone. -* When generating any text (chat messages, PR descriptions, documentation, code comments), use a direct, concise, and technical communication style. Avoid marketing language, hyperbole, and subjective adjectives like 'robust', 'powerful', 'easy', or 'comprehensiverbose'. Focus on factually describing what the code or process does, in a tone similar to technical documentation or a well-written commit message. -* Always debug to break down the problem down to solve the problem at hand: for runtime, adding debugging lines and run the code/tests; for type issues, add debugging types or use internal types to understand where things break down -* When the code needs some context for understanding (theres some inherent complexity not surfaced by the code itself), use this format: - - // context(justinvdm, 5 Feb 2025): Serve assets requests using the assets service binding - // todo(justinvdm, 5 Feb 2025): Find a way to avoid this so asset requests are served directly - // rather than first needing to go through the worker* Work Log Protocol: All development must start by creating/updating a work log in directory `/.notes/justin/worklogs/` directory, with the file name format `YYYY-MM-DD-description.md`. The initial log must define the problem, plan, and context. The log must be updated in real-time throughout the development process (types, tests, implementation) with all notable events: decisions and their rationale, blockers, discoveries, and plan changes. It is a continuous journal. -* Work logs should be written as if by me, appending for each new task, finding, decision, etc. If I ask you to correct a mistake of your own, do not add content on that change in the work log, but instead revise as if that mistake never happened - think of what I would have done in the first place. -* Never say "Final" or "Definitive" or similar. Everything is an attempt, and subject to the test of time. -* Avoid "fluff" at the end of a section intended to round it off. Example (avoid this!): "This approach, combining a high-level stitching strategy with low-level, well-tested extraction utilities, ensures the solution is not only architecturally sound but also maintainable and correct." -* Architecture Revision Protocol: Architecture documents in `/docs/architecture` are to be revised only as the final step, after implementation is stable and tests pass. Use the completed work log as the primary source to distill the final, successful implementation's "why" into the formal documentation, following the established problem/solution narrative format. -* The user prefers technical writing to maintain consistent tone, style, and formatting; use high-level explanations; and avoid references to programming symbols. [[memory:8001383]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001380]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001377]] -* The user prefers a neutral writing tone, including in PR descriptions, avoiding dramatic or hyperbolic language. They avoid specific words that add undue emphasis or urgency, such as “killing,” “unreliable,” “risk,” “obscured,” and “critically.” [[memory:8001374]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:8001371]] -* The user prefers that the assistant adopt a less formal, more human, and casual tone in messages, avoiding stiffness and passive-aggressive phrasing. They also prefer concise, short communications using bullet points and bold keywords, avoiding long-winded explanations, overly dramatic language, and words like “essential” or “critical.” [[memory:6170010]] -* The user prefers that the assistant avoid using the word 'new' in documentation, as it is not important and will quickly become outdated. [[memory:6165420]] -* The user prefers that when modifying documentation, the assistant include all original context and not drop any details. [[memory:4798121]] -* Project uses the debug library for long-term logging with minimal verbosity, logging only failures. [[memory:4586459]] -* The user prefers tentative, exploratory language (“it seems,” “I think,” “might be”) over assertive claims to encourage openness and humility. They always avoid dramatic language and specific words like “killing” and “unreliable.” [[memory:4586455]] -* The user prefers documentation to avoid promotional or selling language and not claim that the architecture is superior. [[memory:4586453]] -* The user prefers using 'rwsdk' as the prefix instead of 'rws' throughout the codebase. [[memory:4586450]] -* When importing from `.mts` source files, use the `.mjs` extension in the import path. TypeScript handles the resolution, so even though the files have a `.mts` extension, the import specifiers must use `.mjs` . [[memory:4544197]] -* Prefer dependency injection over mocking in tests. Dependency injection makes a function's dependencies explicit and allows for passing in controlled versions for testing. Mocking can hide dependencies, lead to leaky state between tests, and make tests more brittle. [[memory:4223216]] -* Architecture documentation should focus on the "why" behind a design decision. It must explain the problem, the constraints considered, and the rationale for the chosen solution. The narrative is as important as the technical description. [[memory:4132497]] -* Architecture documentation should be clear, easy to understand, and avoid unnecessary technical jargon or low-level implementation details like specific function or variable names. The goal is to explain the system's design, not its line-by-line implementation. [[memory:4132491]] -* When making significant changes to the framework's architecture—including adding, modifying, or removing core functionalities—a corresponding entry must be created or updated in the `docs/architecture` directory. [[memory:4132489]] -* The user prefers that the assistant not hardcode values and avoid hardcoded paths or constants. [[memory:4059607]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:3430114]] -* Pipe all your commands through `cat` when possible, ensuring to pipe stderr and stdout, so that we can avoid interactivity on my side being a blocker as much as possible -* If asked to use git worktrees to work on a task, use ~/rw/worktrees// as the dir name -* NEVER use the word "final" -* Everything is an attempt, and subject to the test of time -* For any non-trivial task involving investigation or multiple attempts, create or update a work log to tell the story of the problem-solving journey. Frame the log as a narrative of each attempt, explaining the rationale and the findings that led to the next step, and conclude with the currently accepted solution. Store all work logs in a .worklogs/justin directory at the project root, using the filename format YYYY-MM-DD-short-description.md. -* Don't add comments unless I ask. -* Do this: - -if (foo) { - bar -} - -Do not do this - -if (foo) bar -* All changes that are larger scale, architecturally relevant or affect the behaviour of the system, start with architecture documentation (in docs/architecture/). If there's no relevant doc, create one anew. First make sure the change to be made is documented here correctly. When complete, come up with a list of the tasks to be done to refacor the code to make the necessary changes. Then stop and wait for my approval before proceeding with the corresponding code changes. -* Use ' isntead of ’ -* Use - instead of — -* Style Guide: Plain Technical Communication - - When generating any text (PR descriptions, documentation, code comments, etc.), adhere strictly to the following rules: - - 1. Use Simple, Direct Language: Write for clarity. Avoid jargon and complex vocabulary where a simpler word will do. - 2. Describe Actions, Not Intent: Instead of explaining the purpose or goal of a piece of code (e.g., "to verify integrity"), describe the literal action it performs (e.g., "compares file checksums"). - 3. No Subjective Qualifiers: Do not use adjectives that evaluate quality or value (e.g., good, robust, easy, safe, comprehensive). Stick to objective facts. - 4. Avoid Abstract Concepts: Break down high-level technical concepts into their concrete, constituent steps. For example, instead of "automated verification," state the specific checks that are run: "runs a checksum comparison and smoke tests." - 5. Be Concise: Omit unnecessary words. -* When generating a PR description or similar documentation, structure the text to first explain the problem or the previous state. Then, introduce the solution and describe its key functional outcomes at a high level. Avoid low-level implementation details unless they are essential to understanding the core change. Conclude with the testing status and what still needs to be validated. Maintain a direct and technical tone. -* When generating any text (chat messages, PR descriptions, documentation, code comments), use a direct, concise, and technical communication style. Avoid marketing language, hyperbole, and subjective adjectives like 'robust', 'powerful', 'easy', or 'comprehensiverbose'. Focus on factually describing what the code or process does, in a tone similar to technical documentation or a well-written commit message. -* Always debug to break down the problem down to solve the problem at hand: for runtime, adding debugging lines and run the code/tests; for type issues, add debugging types or use internal types to understand where things break down -* When the code needs some context for understanding (theres some inherent complexity not surfaced by the code itself), use this format: - - // context(justinvdm, 5 Feb 2025): Serve assets requests using the assets service binding - // todo(justinvdm, 5 Feb 2025): Find a way to avoid this so asset requests are served directly - // rather than first needing to go through the worker \ No newline at end of file diff --git a/docs/architecture/documentTransforms.md b/docs/architecture/documentTransforms.md index 2656d1f7c..bafc6f129 100644 --- a/docs/architecture/documentTransforms.md +++ b/docs/architecture/documentTransforms.md @@ -4,16 +4,15 @@ This document details the various automated transformations applied to `Document ## The Challenge: From Source to Production -In our framework, developers define the entire HTML shell using a React component, typically `src/app/Document.tsx`. This provides great power and flexibility, but it also introduces a significant architectural challenge: balancing our philosophy of user control with the technical requirements of a modern React framework. +In our framework, developers define the entire HTML shell using a React component, typically `src/app/Document.tsx`. This provides great power and flexibility, as explained in the [guides for creating Documents](../src/contents/docs/guides/frontend/documents.mdx). However, the source code of a `Document` component is not what can be served directly to a user's browser, especially in a production environment. It contains several elements that need to be processed: -1. **The Hydration Ordering Problem:** For `React.useId` to work correctly, React must inject a hydration "marker" script *before* the main client entry script is loaded. This means React needs to control the rendering of the entry point. However, our philosophy dictates that the user should explicitly place this script in their `Document`. This creates a direct conflict: how can React control a script that the user has placed? -2. **Development-Time Paths**: Script tags like `