docs: add core concepts, resources, support and more#147
Conversation
jyecusch
requested review from
HomelessDinosaur,
davemooreuws,
raksiv,
sean-nitric and
tjholm
|
Note Reviews pausedUse the following commands to manage reviews:
📝 WalkthroughWalkthroughAdds a large documentation expansion: 30+ new MDX pages across Deploy (AWS, GCP, Azure, Terraform configuration, environment management), Develop (services, entrypoints, buckets, databases, access control, generated clients), Foundations (projects, platforms, plugins, infrastructure generation, local development, deployment), Guides (static website hosting, plugin development), SDK docs (Node/Python/Go clients & DBs), FAQ, Support, Why Suga; updates site navigation (docs/docs.json) including redirects; and extends the Vale accepted vocabulary file (docs/.vale/styles/config/vocabularies/Suga/accept.txt). Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks✅ Passed checks (3 passed)
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: 14
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/docs.json (1)
14-220: Createdocs/develop/environment-variables.mdxor remove it from the navigation.The page
develop/environment-variablesis referenced in docs.json (line 46 in the Develop group) but the file doesn't exist indocs/develop/. This will break navigation. Either create the missing file or remove the reference from docs.json.
🧹 Nitpick comments (2)
docs/foundations/deployment.mdx (1)
278-280: Clarify Azure platform support status.The Azure card is included alongside AWS and GCP, but per project learnings, Azure is not officially supported as a deployment target. Consider adding a note to the Azure card or the "Cloud Provider Setup" section clarifying that Azure support is in progress, to align with the placeholder page's messaging.
docs/develop/services.mdx (1)
88-89: Tighten the language and fix grammar.Line 88-89: Change "In order to establish HTTP routes/requests Suga will" to improve conciseness and add missing punctuation:
-#### PORT environment variable - -In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. +#### PORT environment variable + +To establish HTTP routes/requests, Suga automatically injects a `PORT` env var into each of your services, indicating which port it should start on.This removes wordiness and adds the comma flagged by the static analysis tool.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/develop/access-control/service-to-bucket-access-control.pngis excluded by!**/*.pngdocs/images/develop/app-diagram-example.pngis excluded by!**/*.png
📒 Files selected for processing (34)
docs/deploy/aws.mdx(1 hunks)docs/deploy/azure.mdx(1 hunks)docs/deploy/environment-management.mdx(1 hunks)docs/deploy/gcp.mdx(1 hunks)docs/deploy/overview.mdx(1 hunks)docs/deploy/terraform-configuration.mdx(1 hunks)docs/develop/access-control.mdx(1 hunks)docs/develop/buckets.mdx(1 hunks)docs/develop/databases.mdx(1 hunks)docs/develop/entrypoints.mdx(1 hunks)docs/develop/overview.mdx(1 hunks)docs/develop/services.mdx(1 hunks)docs/develop/suga-client.mdx(1 hunks)docs/docs.json(3 hunks)docs/faq.mdx(1 hunks)docs/foundations/deployment.mdx(1 hunks)docs/foundations/infrastructure-generation.mdx(1 hunks)docs/foundations/local-development.mdx(1 hunks)docs/foundations/overview.mdx(1 hunks)docs/foundations/platforms.mdx(2 hunks)docs/foundations/plugins.mdx(1 hunks)docs/foundations/projects.mdx(1 hunks)docs/guides/build-platform.mdx(4 hunks)docs/guides/plugin-development.mdx(4 hunks)docs/guides/static-website-hosting.mdx(1 hunks)docs/quickstart.mdx(1 hunks)docs/sdks/go/client.mdx(1 hunks)docs/sdks/go/databases.mdx(1 hunks)docs/sdks/node/client.mdx(1 hunks)docs/sdks/node/databases.mdx(1 hunks)docs/sdks/python/client.mdx(1 hunks)docs/sdks/python/databases.mdx(1 hunks)docs/support.mdx(1 hunks)docs/why-suga.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/deploy/azure.mdxdocs/deploy/aws.mdxdocs/faq.mdxdocs/quickstart.mdxdocs/deploy/gcp.mdxdocs/deploy/overview.mdxdocs/foundations/platforms.mdxdocs/why-suga.mdx
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/foundations/overview.mdxdocs/faq.mdxdocs/quickstart.mdxdocs/foundations/infrastructure-generation.mdxdocs/sdks/node/client.mdxdocs/foundations/local-development.mdxdocs/why-suga.mdxdocs/guides/static-website-hosting.mdx
📚 Learning: 2025-09-22T21:56:58.994Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.994Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
Applied to files:
docs/quickstart.mdxdocs/docs.json
📚 Learning: 2025-08-27T03:55:50.432Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:25-34
Timestamp: 2025-08-27T03:55:50.432Z
Learning: In the Suga project, the default directory for CDKTF synthesized output is `terraform/`, not `cdktf.out/`. The directory structure is terraform/stacks/<stack_name>/ containing the generated Terraform configurations.
Applied to files:
docs/foundations/infrastructure-generation.mdxdocs/foundations/platforms.mdx
📚 Learning: 2025-09-23T23:36:19.429Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 74
File: cli/internal/simulation/simulation.go:85-85
Timestamp: 2025-09-23T23:36:19.429Z
Learning: In the Suga CLI, there are two different contexts for SugaIntro Dashboard output: 1) Simulation server (simulation.go) where Dashboard was correctly removed because it was non-functional, and 2) Development WebSocket server (suga.go) where Dashboard URL is valid and needed for syncing with the dashboard using team slug and port parameters.
Applied to files:
docs/foundations/local-development.mdx
🪛 GitHub Actions: Test Docs
docs/sdks/node/databases.mdx
[error] 60-60: [Vale.Spelling] Did you really mean 'Prisma'?
docs/develop/databases.mdx
[error] 201-201: [Vale.Spelling] Did you really mean 'Prisma'?
[error] 201-201: [Vale.Spelling] Did you really mean 'SQLAlchemy'?
[error] 206-206: [Vale.Spelling] Did you really mean 'datasource'?
[error] 227-227: [Vale.Spelling] Did you really mean 'sqlalchemy'?
[error] 250-250: [Vale.Spelling] Did you really mean 'ORMs'?
docs/sdks/python/databases.mdx
[error] 63-63: [Vale.Spelling] Did you really mean 'SQLAlchemy'?
docs/develop/overview.mdx
[error] 110-110: [Vale.Spelling] Did you really mean 'Minio'?
docs/sdks/go/databases.mdx
[error] 23-23: [Vale.Spelling] Did you really mean 'pgx'?
[error] 119-119: [Vale.Spelling] Did you really mean 'sqlx'?
[error] 198-198: [Vale.Spelling] Did you really mean 'pgxpool'?
docs/develop/services.mdx
[error] 116-116: [Vale.Spelling] Did you really mean 'Monorepo'?
[error] 118-118: [Vale.Spelling] Did you really mean 'monorepo'?
docs/foundations/local-development.mdx
[error] 219-219: [Vale.Spelling] Did you really mean 'api'?
[error] 221-221: [Vale.Spelling] Did you really mean 'debugpy'?
[error] 229-229: [Vale.Spelling] Did you really mean 'dlv'?
docs/why-suga.mdx
[error] 26-26: [Vale.Spelling] Did you really mean 'playsInline'?
[error] 111-111: [Vale.Spelling] Did you really mean 'Reusability'?
[error] 127-127: [Vale.Spelling] Did you really mean 'Pulumi'?
[error] 130-130: [Vale.Spelling] Did you really mean 'SREs'?
[error] 132-132: [Vale.Spelling] Did you really mean 'SREs'?
🪛 GitHub Check: Spell Check with Vale
docs/develop/databases.mdx
[failure] 250-250:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'ORMs'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'ORMs'?", "location": {"path": "docs/develop/databases.mdx", "range": {"start": {"line": 250, "column": 41}}}, "severity": "ERROR"}
[failure] 227-227:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'sqlalchemy'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'sqlalchemy'?", "location": {"path": "docs/develop/databases.mdx", "range": {"start": {"line": 227, "column": 10}}}, "severity": "ERROR"}
[failure] 206-206:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'datasource'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'datasource'?", "location": {"path": "docs/develop/databases.mdx", "range": {"start": {"line": 206, "column": 5}}}, "severity": "ERROR"}
[failure] 201-201:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'SQLAlchemy'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'SQLAlchemy'?", "location": {"path": "docs/develop/databases.mdx", "range": {"start": {"line": 201, "column": 76}}}, "severity": "ERROR"}
[failure] 201-201:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Prisma'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Prisma'?", "location": {"path": "docs/develop/databases.mdx", "range": {"start": {"line": 201, "column": 59}}}, "severity": "ERROR"}
docs/develop/overview.mdx
[failure] 110-110:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Minio'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Minio'?", "location": {"path": "docs/develop/overview.mdx", "range": {"start": {"line": 110, "column": 158}}}, "severity": "ERROR"}
docs/develop/services.mdx
[failure] 118-118:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'monorepo'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'monorepo'?", "location": {"path": "docs/develop/services.mdx", "range": {"start": {"line": 118, "column": 48}}}, "severity": "ERROR"}
[failure] 116-116:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Monorepo'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Monorepo'?", "location": {"path": "docs/develop/services.mdx", "range": {"start": {"line": 116, "column": 6}}}, "severity": "ERROR"}
docs/foundations/local-development.mdx
[failure] 219-219:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api'?
Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api'?", "location": {"path": "docs/foundations/local-development.mdx", "range": {"start": {"line": 219, "column": 7}}}, "severity": "ERROR"}
🪛 LanguageTool
docs/foundations/overview.mdx
[uncategorized] ~68-~68: When ‘provision-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...locks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: ...
(SPECIFIC_HYPHEN)
docs/develop/databases.mdx
[grammar] ~28-~28: Uncountable nouns are usually not used with an indefinite article. Use simply “service access”.
Context: ... and Connection Strings When you grant a service access to a database, Suga automatically injec...
(A_UNCOUNTABLE)
[uncategorized] ~72-~72: Possible missing comma found.
Context: ... env_var_key: ORDERS_DATABASE_URL ``` Now the api service receives three separa...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/faq.mdx
[uncategorized] ~38-~38: Possible missing preposition found.
Context: ...dd-suga) guide. ### Do I need to learn Terraform? No, but understanding Terraform basic...
(AI_HYDRA_LEO_MISSING_TO)
[typographical] ~87-~87: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...oes deployment take? First deployment: 5-15 minutes (Terraform provisioning cloud r...
(HYPHEN_TO_EN)
[typographical] ~88-~88: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...isioning cloud resources) Code updates: 1-5 minutes (depends on service type and cl...
(HYPHEN_TO_EN)
[grammar] ~100-~100: The word “rollback” is a noun. The verb is spelled with a space.
Context: ...orm workspace new dev ``` ### How do I rollback a deployment? Revert your code changes...
(NOUN_VERB_CONFUSION)
[uncategorized] ~119-~119: A comma may be missing after the conjunctive/linking adverb ‘Currently’.
Context: ... services communicate with each other? Currently services communicate through shared dat...
(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
[uncategorized] ~128-~128: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...icial platforms 4. Extend Suga through [open source contributions](https://github.com/nitri...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/guides/build-platform.mdx
[uncategorized] ~47-~47: When ‘application-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... Templates that define how to provision application specific resources, such as services, databases,...
(SPECIFIC_HYPHEN)
docs/develop/overview.mdx
[misspelling] ~71-~71: This word is normally spelled as one.
Context: ...guration - Automatic YAML sync with bi-directional live update to your project's suga.yaml...
(EN_COMPOUNDS_BI_DIRECTIONAL)
[typographical] ~104-~104: The word “however” is an adverb that can’t be used like a conjunction, and therefore needs to be separated from the sentence.
Context: ...ce type has unique configuration options, however there are some common configuration opt...
(HOWEVER_SENTENCE)
[uncategorized] ~108-~108: The preposition ‘at’ seems more likely in this position.
Context: ... more. The list gets longer as you look to other cloud providers. The same is tru...
(AI_HYDRA_LEO_REPLACE_TO_AT)
docs/foundations/plugins.mdx
[grammar] ~160-~160: The word ‘reference’ is a noun or an adjective. A verb or adverb is missing or misspelled here, or maybe a comma is missing.
Context: ...expose outputs that other resources can reference: ```hcl title="Lambda plugin outputs" ...
(PRP_MD_NN)
docs/develop/services.mdx
[style] ~88-~88: Consider a more concise word here.
Context: ...e" ``` #### PORT environment variable In order to establish HTTP routes/requests Suga wil...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~89-~89: Possible missing comma found.
Context: ...able In order to establish HTTP routes/requests Suga will automatically inject a PORT...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/foundations/infrastructure-generation.mdx
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...The suga build command orchestrates a multi-step process: <Step title="Load P...
(EN_COMPOUNDS_MULTI_STEP)
docs/foundations/local-development.mdx
[grammar] ~139-~139: The singular proper name ‘PostgreSQL’ must be used with a third-person or a past tense verb.
Context: ...` Features: - Automatic PostgreSQL instance per database - Connection strings injec...
(HE_VERB_AGR)
docs/guides/static-website-hosting.mdx
[misspelling] ~99-~99: This word is normally spelled as one.
Context: ...i-Page Applications Deploy traditional multi-page websites: ```yaml buckets: website: ...
(EN_COMPOUNDS_MULTI_PAGE)
docs/foundations/deployment.mdx
[style] ~170-~170: Consider shortening or rephrasing this to strengthen your wording.
Context: ...### Updating Your Application When you make changes to your project: 1. **Rebuild Terraform:*...
(MAKE_CHANGES)
[uncategorized] ~285-~285: Possible missing comma found.
Context: ... carefully. By default, state is stored locally which is suitable for personal projects...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (33)
docs/foundations/projects.mdx (1)
2-2: Navigation paths updated correctly.Link target and title align with the new foundations-based documentation structure.
Also applies to: 10-10
docs/sdks/node/client.mdx (1)
1-39: Clear, concise introduction to the Node.js client.Good foundational documentation with working examples and appropriate cross-links to related SDK pages.
docs/deploy/environment-management.mdx (1)
1-35: Practical environment management guide.Clear Terraform patterns with realistic examples. Complements the terraform-configuration.mdx page well.
docs/deploy/terraform-configuration.mdx (1)
1-22: Good organizational hub for Terraform guidance.Clean structure that effectively points readers to detailed pages. Links are correct and well-integrated.
docs/sdks/go/databases.mdx (1)
1-228: Comprehensive and accurate Go database documentation.Excellent coverage of pgx, GORM, and sqlx with proper connection pooling and multi-database patterns. Mirrors the quality of Node.js and Python docs added in the same PR. Code examples follow Go best practices.
docs/sdks/node/databases.mdx (1)
1-195: Excellent Node.js/TypeScript database guide.Well-structured with solid coverage of pg, Prisma, and TypeORM. Consistent approach with Go and Python docs. Connection pooling guidance is practical.
docs/develop/suga-client.mdx (1)
1-250: Comprehensive guide to Suga Client Libraries.Excellent documentation covering why to use generated clients, multi-language examples, cloud portability, local development, and when to use native SDKs. Well-structured with clear comparisons and ASCII architecture diagrams.
Verify that all hrefs in the CardGroup (lines 234–250) resolve to existing pages:
/sdks(SDK overview/index)/foundations/local-development/cli/generate/develop/access-controlThis ensures navigation is complete in the new documentation structure.
docs/sdks/python/databases.mdx (1)
1-189: Solid Python database guide across three ORMs/drivers.Good coverage of psycopg2, SQLAlchemy, and Django. Consistent approach with Node.js and Go docs. Connection pooling pattern is clear and practical.
docs/foundations/deployment.mdx (1)
1-50: Solid structure and component usage.The deployment lifecycle steps are well-organized using Mintlify's
<Steps>component. Cross-file links are accurate, and the split between overview and platform-specific guides (AWS, GCP, Azure) follows a logical information architecture. Based on learnings, Mintlify components like<Steps>and<Step>are built-in and don't require imports—good usage here.docs/develop/services.mdx (2)
116-118: Resolve Vale spelling check for "monorepo".The pipeline reports Vale.Spelling errors on "Monorepo" (line 116) and "monorepo" (line 118). "Monorepo" is standard industry terminology but may need alternate phrasing to satisfy your Vale configuration. Options include: "mono-repo", "monorepo setup", or context-dependent rewording. Check your Vale dictionary/config to confirm the expected form.
1-115: Well-structured services documentation.Clear examples of dev scripts, container config, environment variables, and working directories. The monorepo section—once the spelling issue is resolved—is valuable and realistic. Links to related guides (Access Control, Local Development, Suga Client, Databases) are accurate.
docs/quickstart.mdx (1)
378-379: Navigation links correctly updated.The updated paths
/foundations/projectsand/foundations/platformsalign with the documented navigation reorganization and match the new file locations. Redirects in docs.json ensure backward compatibility.docs/deploy/azure.mdx (1)
1-14: Appropriate placeholder for unsupported platform.The Azure deployment file transparently communicates "in progress" status and provides a user contact path. This aligns with learnings that Azure support is not yet available. The placeholder approach prevents confusion about current capabilities.
docs/sdks/go/client.mdx (1)
1-56: Clean and consistent SDK documentation.The Go client guide follows the same pattern as Python and Node.js SDKs with clear installation, basic usage, and navigation to related resources. Code example is realistic and Learn More links are accurate.
docs/deploy/gcp.mdx (1)
1-41: Solid GCP quick start guide.Prerequisites are accurate, Quick Start steps are concise, and the link to the complete deployment guide provides path to deeper learning. Terraform configuration example is appropriately GCP-specific (project_id, region).
docs/deploy/aws.mdx (1)
1-41: Well-structured AWS quick start.Prerequisites, Quick Start steps, and provider configuration are accurate and concise. The card linking to the complete deployment guide provides clear navigation path to deeper workflows. Parallel structure with GCP guide promotes consistency.
docs/sdks/python/client.mdx (1)
1-39: Clean Python SDK documentation.Installation, basic usage, and Learn More cards are consistent with other language SDK guides. Code example is clear and the links to storage and database SDKs provide expected navigation paths.
docs/develop/buckets.mdx (1)
1-164: Well-structured bucket documentation. Clear progression from concept through configuration to code examples across all supported languages. Uses Mintlify components correctly and provides practical guidance on local emulation.docs/foundations/platforms.mdx (2)
1-9: Updated links align with foundations restructuring. The navigation updates from/projectsto/foundations/projectsare consistent with the reorganized documentation structure shown in the PR summary.
36-38: Verify Azure support status in line 38. The file states "Azure Platform (coming soon)" but review learnings from a prior PR indicate Azure is not yet officially supported as a deployment target. Confirm this reflects current roadmap before merge.docs/deploy/overview.mdx (1)
1-30: Clean deployment overview. Effective landing page that routes users to provider-specific guides and terraform configuration. Uses Mintlify components appropriately.docs/foundations/plugins.mdx (1)
1-279: Thorough plugin system documentation. Excellent technical depth covering plugin structure, types, official libraries, configuration, outputs, runtime adapters, and versioning. Code examples and tables effectively illustrate concepts. The LanguageTool grammar flag on line 160 appears to be a false positive.docs/develop/databases.mdx (1)
201-227: Vale spell-check failures on legitimate technical terms. The pipeline is failing on proper nouns and technical terminology (Prisma, SQLAlchemy, datasource, ORMs) that are correct in context. These should either be added to the project's Vale configuration exception list or the Vale ruleset should be adjusted to allow common framework and package names. The content itself is accurate.Also applies to: 250-250
docs/support.mdx (1)
1-89: Well-organized support landing page. Clear routing to documentation, support channels (email, GitHub), enterprise options, and community resources. Effective use of CardGroup to highlight primary documentation entry points.docs/develop/entrypoints.mdx (1)
1-99: Clear entrypoints guide with practical patterns. Effectively explains routing mechanics with concrete examples. The common patterns section (API+Frontend, microservices gateway, static site) provides helpful reference scenarios. Cross-links to related resources are well-chosen.docs/why-suga.mdx (1)
26-26: False positive: Vale spell check on HTML5 attribute.
playsInlineis a valid HTML5 video element attribute. This is a Vale configuration false positive; no action needed.docs/guides/plugin-development.mdx (1)
816-816: Link path verified—no issues found.The reference to
/foundations/platformsis valid; the file exists atdocs/foundations/platforms.mdx.docs/develop/access-control.mdx (1)
89-89: Cross-reference paths verified.Both
/foundations/pluginsand/deploy/awsexist and are correctly referenced.docs/foundations/overview.mdx (1)
12-22: No issues found—Mermaid diagram syntax is consistent with existing working diagrams.The script output confirms Mermaid rendering is already enabled and functioning across the documentation system. The diagram uses the same
graph TBsyntax as other validated files in the codebase.docs/foundations/local-development.mdx (2)
1-348: Excellent documentation structure and content quality.The documentation is comprehensive, well-organized, and clearly explains local development workflows. The use of Mintlify components (Tabs, Cards, Warning, Info, Tip) is correct and provides good UX. Examples are clear with appropriate language annotations, and cross-references to related docs are well-placed.
Based on learnings: confirmed correct usage of Mintlify's built-in MDX components without unnecessary imports.
219-229: Resolve pipeline failures from Vale spell checker.Three Vale spelling checks are failing on legitimate code identifiers (
api,debugpy,dlv). These appear to be false positives from the spell checker flagging package names and configuration keys.These must be resolved before merge. Verify whether the Vale configuration excludes code blocks and YAML contexts, or if spell-check rules need updating to recognize these as legitimate identifiers. You may need to:
- Configure Vale to skip code block context (
apiin YAML,debugpypackage name,dlvdebugger)- Add these terms to a Vale exception list
- Wrap identifiers in code fences if not already present
⛔ Skipped due to learnings
Learnt from: jyecusch Repo: nitrictech/suga PR: 117 File: docs/guides/terraform-backend-config.mdx:62-116 Timestamp: 2025-10-14T03:30:51.181Z Learning: Do not create review comments for issues (such as Vale spelling failures, linting errors, or other CI check failures) that are already clearly reported in failed GitHub Actions or CI pipelines, as this creates redundant noise.docs/docs.json (2)
21-78: Navigation restructuring aligns well with PR objectives.The reorganization into Foundations, Develop, and Deploy groups provides clear separation of concerns and improves discoverability. The expanded Guides and updated Resources sections support the documentation refresh. New redirects on lines 211-220 provide backward compatibility for moved pages.
123-149: SDK section expansion with language-specific subsections looks good.The Python, Node.js, and Go sections now have consistent subsections (client, storage, databases) which improves navigability and documentation parity across languages.
jyecusch
force-pushed
the
docs/refine-structure
branch
from
141d3c4 to
b77e7fa
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/docs.json (1)
1-221: Createdocs/develop/environment-variables.mdxor remove the reference from docs.json.The file
docs/develop/environment-variables.mdxis referenced in the navigation (line 38) but doesn't exist in the repository. This will cause a broken link when the documentation is deployed.
♻️ Duplicate comments (9)
docs/faq.mdx (5)
38-40: Fix missing preposition.Line 38 should read "understanding Terraform basics can help when customizing deployments" to complete the thought.
- No, but understanding Terraform basics helps when customizing deployments. + No, but understanding Terraform basics can help when customizing deployments.
87-88: Use en-dashes for ranges.Replace hyphens with en-dashes per typographic conventions:
- First deployment: 5-15 minutes (Terraform provisioning cloud resources) - Code updates: 1-5 minutes (depends on service type and cloud provider) + First deployment: 5–15 minutes (Terraform provisioning cloud resources) + Code updates: 1–5 minutes (depends on service type and cloud provider)
100-102: Fix noun/verb confusion."Rollback" is a noun; use the verb phrase "roll back" instead:
- ### How do I rollback a deployment? + ### How do I roll back a deployment?
119-120: Add comma after conjunctive adverb.Insert a comma after "Currently" per grammar guidelines:
- Currently services communicate through shared databases or buckets. + Currently, services communicate through shared databases or buckets.
128-128: Hyphenate compound adjective."Open source" modifying "contributions" should be hyphenated:
- 4. Extend Suga through [open source contributions](https://github.com/nitrictech/suga) + 4. Extend Suga through [open-source contributions](https://github.com/nitrictech/suga)docs/develop/overview.mdx (2)
71-71: Spell "bidirectional" as one word.- - **Automatic YAML sync** with bi-directional live update to your project's suga.yaml file + - **Automatic YAML sync** with bidirectional live update to your project's suga.yaml file
104-104: Separate conjunctive adverb with semicolon."However" requires separation from the preceding clause:
- Each resource type has unique configuration options, however there are some common configuration options. + Each resource type has unique configuration options; however, there are some common configuration options.docs/foundations/deployment.mdx (1)
283-286: Add missing comma for clarity. Line 285 needs a comma after "locally" for a non-restrictive clause:-Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally which is suitable for personal projects but not recommended for teams. +Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally, which is suitable for personal projects but not recommended for teams.docs/foundations/local-development.mdx (1)
138-142: Fix grammar in bullet point. Line 139 lacks a verb and creates a subject-verb disagreement. Restructure as:-**Features:** -- Automatic PostgreSQL instance per database -- Connection strings injected into services via environment variables -- Data persists between `suga dev` sessions -- Full PostgreSQL compatibility for development +**Features:** +- Automatic PostgreSQL instance created per database +- Connection strings injected into services via environment variables +- Data persists between `suga dev` sessions +- Full PostgreSQL compatibility for development
🧹 Nitpick comments (3)
docs/guides/static-website-hosting.mdx (1)
99-99: Hyphenate compound adjective in heading."Multi-page" used as an adjective should be hyphenated:
- ## Multi-Page Applications + ## Multi-page applicationsdocs/guides/build-platform.mdx (1)
45-48: Add hyphen to compound adjective. Line 47 should use "application-specific" (hyphenated) when modifying the noun "resources."Apply this diff:
-- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application specific resources, such as services, databases, buckets, and entrypoints +- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application-specific resources, such as services, databases, buckets, and entrypointsdocs/develop/services.mdx (1)
87-90: Simplify and clarify. The phrasing is wordy and unclear. Rewrite for conciseness:-#### PORT environment variable - -In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. +#### PORT environment variable + +Suga automatically injects a `PORT` environment variable into each service to establish HTTP routes, indicating which port to listen on.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/develop/access-control/service-to-bucket-access-control.pngis excluded by!**/*.pngdocs/images/develop/app-diagram-example.pngis excluded by!**/*.png
📒 Files selected for processing (35)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/deploy/aws.mdx(1 hunks)docs/deploy/azure.mdx(1 hunks)docs/deploy/environment-management.mdx(1 hunks)docs/deploy/gcp.mdx(1 hunks)docs/deploy/overview.mdx(1 hunks)docs/deploy/terraform-configuration.mdx(1 hunks)docs/develop/access-control.mdx(1 hunks)docs/develop/buckets.mdx(1 hunks)docs/develop/databases.mdx(1 hunks)docs/develop/entrypoints.mdx(1 hunks)docs/develop/overview.mdx(1 hunks)docs/develop/services.mdx(1 hunks)docs/develop/suga-client.mdx(1 hunks)docs/docs.json(3 hunks)docs/faq.mdx(1 hunks)docs/foundations/deployment.mdx(1 hunks)docs/foundations/infrastructure-generation.mdx(1 hunks)docs/foundations/local-development.mdx(1 hunks)docs/foundations/overview.mdx(1 hunks)docs/foundations/platforms.mdx(2 hunks)docs/foundations/plugins.mdx(1 hunks)docs/foundations/projects.mdx(1 hunks)docs/guides/build-platform.mdx(4 hunks)docs/guides/plugin-development.mdx(4 hunks)docs/guides/static-website-hosting.mdx(1 hunks)docs/quickstart.mdx(1 hunks)docs/sdks/go/client.mdx(1 hunks)docs/sdks/go/databases.mdx(1 hunks)docs/sdks/node/client.mdx(1 hunks)docs/sdks/node/databases.mdx(1 hunks)docs/sdks/python/client.mdx(1 hunks)docs/sdks/python/databases.mdx(1 hunks)docs/support.mdx(1 hunks)docs/why-suga.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (18)
- docs/quickstart.mdx
- docs/why-suga.mdx
- docs/sdks/node/client.mdx
- docs/develop/access-control.mdx
- docs/support.mdx
- docs/sdks/go/databases.mdx
- docs/develop/suga-client.mdx
- docs/deploy/gcp.mdx
- docs/foundations/platforms.mdx
- docs/foundations/projects.mdx
- docs/deploy/environment-management.mdx
- docs/guides/plugin-development.mdx
- docs/develop/entrypoints.mdx
- docs/sdks/node/databases.mdx
- docs/deploy/aws.mdx
- docs/sdks/python/client.mdx
- docs/sdks/go/client.mdx
- docs/develop/buckets.mdx
🧰 Additional context used
🧠 Learnings (6)
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/foundations/overview.mdxdocs/foundations/infrastructure-generation.mdxdocs/foundations/local-development.mdxdocs/faq.mdxdocs/guides/static-website-hosting.mdx
📚 Learning: 2025-08-27T03:55:50.432Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:25-34
Timestamp: 2025-08-27T03:55:50.432Z
Learning: In the Suga project, the default directory for CDKTF synthesized output is `terraform/`, not `cdktf.out/`. The directory structure is terraform/stacks/<stack_name>/ containing the generated Terraform configurations.
Applied to files:
docs/foundations/infrastructure-generation.mdx
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/deploy/overview.mdxdocs/deploy/azure.mdxdocs/faq.mdx
📚 Learning: 2025-09-22T21:56:58.994Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.994Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
Applied to files:
docs/docs.json
📚 Learning: 2025-09-23T23:36:19.429Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 74
File: cli/internal/simulation/simulation.go:85-85
Timestamp: 2025-09-23T23:36:19.429Z
Learning: In the Suga CLI, there are two different contexts for SugaIntro Dashboard output: 1) Simulation server (simulation.go) where Dashboard was correctly removed because it was non-functional, and 2) Development WebSocket server (suga.go) where Dashboard URL is valid and needed for syncing with the dashboard using team slug and port parameters.
Applied to files:
docs/foundations/local-development.mdx
📚 Learning: 2025-11-11T07:44:40.142Z
Learnt from: tjholm
Repo: nitrictech/suga PR: 147
File: docs/develop/databases.mdx:28-28
Timestamp: 2025-11-11T07:44:40.142Z
Learning: In Suga, "service" is a countable noun. A Suga application is composed of one or more "services", so phrases like "a service" or "grant a service access" are grammatically correct.
Applied to files:
docs/develop/databases.mdxdocs/develop/services.mdx
🪛 LanguageTool
docs/.vale/styles/config/vocabularies/Suga/accept.txt
[duplication] ~287-~287: Possible typo: you repeated a word.
Context: ...ars todo href lang nav prev next toc uv Monorepo monorepo Minio Prisma SQLAlchemy datasource sqla...
(ENGLISH_WORD_REPEAT_RULE)
docs/foundations/overview.mdx
[uncategorized] ~68-~68: When ‘provision-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...locks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: ...
(SPECIFIC_HYPHEN)
docs/foundations/infrastructure-generation.mdx
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...The suga build command orchestrates a multi-step process: <Step title="Load P...
(EN_COMPOUNDS_MULTI_STEP)
docs/foundations/deployment.mdx
[style] ~170-~170: Consider shortening or rephrasing this to strengthen your wording.
Context: ...### Updating Your Application When you make changes to your project: 1. **Rebuild Terraform:*...
(MAKE_CHANGES)
[uncategorized] ~285-~285: Possible missing comma found.
Context: ... carefully. By default, state is stored locally which is suitable for personal projects...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/foundations/plugins.mdx
[grammar] ~160-~160: The word ‘reference’ is a noun or an adjective. A verb or adverb is missing or misspelled here, or maybe a comma is missing.
Context: ...expose outputs that other resources can reference: ```hcl title="Lambda plugin outputs" ...
(PRP_MD_NN)
docs/guides/build-platform.mdx
[uncategorized] ~47-~47: When ‘application-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... Templates that define how to provision application specific resources, such as services, databases,...
(SPECIFIC_HYPHEN)
docs/foundations/local-development.mdx
[grammar] ~139-~139: The singular proper name ‘PostgreSQL’ must be used with a third-person or a past tense verb.
Context: ...` Features: - Automatic PostgreSQL instance per database - Connection strings injec...
(HE_VERB_AGR)
docs/develop/databases.mdx
[grammar] ~28-~28: Uncountable nouns are usually not used with an indefinite article. Use simply “service access”.
Context: ... and Connection Strings When you grant a service access to a database, Suga automatically injec...
(A_UNCOUNTABLE)
[uncategorized] ~72-~72: Possible missing comma found.
Context: ... env_var_key: ORDERS_DATABASE_URL ``` Now the api service receives three separa...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/faq.mdx
[uncategorized] ~38-~38: Possible missing preposition found.
Context: ...dd-suga) guide. ### Do I need to learn Terraform? No, but understanding Terraform basic...
(AI_HYDRA_LEO_MISSING_TO)
[typographical] ~87-~87: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...oes deployment take? First deployment: 5-15 minutes (Terraform provisioning cloud r...
(HYPHEN_TO_EN)
[typographical] ~88-~88: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...isioning cloud resources) Code updates: 1-5 minutes (depends on service type and cl...
(HYPHEN_TO_EN)
[grammar] ~100-~100: The word “rollback” is a noun. The verb is spelled with a space.
Context: ...orm workspace new dev ``` ### How do I rollback a deployment? Revert your code changes...
(NOUN_VERB_CONFUSION)
[uncategorized] ~119-~119: A comma may be missing after the conjunctive/linking adverb ‘Currently’.
Context: ... services communicate with each other? Currently services communicate through shared dat...
(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
[uncategorized] ~128-~128: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...icial platforms 4. Extend Suga through [open source contributions](https://github.com/nitri...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/develop/overview.mdx
[misspelling] ~71-~71: This word is normally spelled as one.
Context: ...guration - Automatic YAML sync with bi-directional live update to your project's suga.yaml...
(EN_COMPOUNDS_BI_DIRECTIONAL)
[typographical] ~104-~104: The word “however” is an adverb that can’t be used like a conjunction, and therefore needs to be separated from the sentence.
Context: ...ce type has unique configuration options, however there are some common configuration opt...
(HOWEVER_SENTENCE)
[uncategorized] ~108-~108: The preposition ‘at’ seems more likely in this position.
Context: ... more. The list gets longer as you look to other cloud providers. The same is tru...
(AI_HYDRA_LEO_REPLACE_TO_AT)
docs/develop/services.mdx
[style] ~88-~88: Consider a more concise word here.
Context: ...e" ``` #### PORT environment variable In order to establish HTTP routes/requests Suga wil...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~89-~89: Possible missing comma found.
Context: ...able In order to establish HTTP routes/requests Suga will automatically inject a PORT...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/guides/static-website-hosting.mdx
[misspelling] ~99-~99: This word is normally spelled as one.
Context: ...i-Page Applications Deploy traditional multi-page websites: ```yaml buckets: website: ...
(EN_COMPOUNDS_MULTI_PAGE)
🔇 Additional comments (7)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)
287-306: Vocabulary additions appropriately support expanded documentation scope.The 19 new terms reflect the deployment (Pulumi, DevOps, SREs), database (Prisma, SQLAlchemy, pgx, sqlx), infrastructure (Monorepo, Minio), and SDK coverage introduced in this PR. The pattern of including both case variants (e.g., "Monorepo"/"monorepo", "SQLAlchemy"/"sqlalchemy") is consistent with the existing vocabulary structure. The static analysis duplication warning is a false positive from a tool designed for prose rather than vocabulary lists.
docs/sdks/python/databases.mdx (1)
63-101: Verify Vale vocabulary whitelist includes "SQLAlchemy".Past reviews flagged that "SQLAlchemy" (the official ORM name, lines 63 and onwards) causes Vale.Spelling pipeline errors due to missing vocabulary entry. Ensure
docs/.vale/styles/config/vocabularies/Suga/accept.txtincludes "SQLAlchemy" on its own line to prevent pipeline failures.docs/deploy/azure.mdx (1)
1-14: Appropriate placeholder for future Azure support.The "coming soon" messaging aligns with current platform support status (AWS and GCP only). Content is clear and guides users to contact support for interest.
docs/deploy/terraform-configuration.mdx (1)
1-22: Solid reference for Terraform configuration.Clean, focused guidance on backends and workspaces with appropriate cross-references to deeper guides.
docs/foundations/infrastructure-generation.mdx (1)
1-197: LGTM. Well-structured documentation with accurate Terraform directory structure and proper cross-linking.docs/deploy/overview.mdx (1)
14-30: Verify Azure support status before release. Based on learnings, Azure is not yet officially supported by Suga—only AWS and GCP are. Presenting Azure alongside supported platforms in the Quick Links may mislead users. Either remove this entry or clearly mark it as "Coming Soon" / "Unsupported" before publication.docs/foundations/overview.mdx (1)
1-298: Excellent foundational overview. Clear architecture explanation, well-organized sections, and proper cross-linking. The Mermaid diagram effectively visualizes the three-layer architecture.
jyecusch
force-pushed
the
docs/refine-structure
branch
from
b77e7fa to
c126825
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/foundations/deployment.mdx (1)
285-285: Add missing comma for clarity.When "which" introduces a non-restrictive clause, a comma should precede it.
-Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally which is suitable for personal projects but not recommended for teams. +Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally, which is suitable for personal projects but not recommended for teams.
🧹 Nitpick comments (7)
docs/faq.mdx (2)
87-88: Use en-dashes for numeric ranges.Replace hyphens with en-dashes in time ranges per typographic conventions.
- First deployment: 5-15 minutes (Terraform provisioning cloud resources) - Code updates: 1-5 minutes (depends on service type and cloud provider) + First deployment: 5–15 minutes (Terraform provisioning cloud resources) + Code updates: 1–5 minutes (depends on service type and cloud provider)
128-128: Hyphenate compound adjective."Open source" modifying the noun "contributions" should be hyphenated.
- 4. Extend Suga through [open source contributions](https://github.com/nitrictech/suga) + 4. Extend Suga through [open-source contributions](https://github.com/nitrictech/suga)docs/sdks/python/databases.mdx (1)
63-101: Add "SQLAlchemy" to Vale vocabulary whitelist.The documentation uses SQLAlchemy (the official Python SQL toolkit), which triggers a Vale.Spelling error in the pipeline. Update
docs/.vale/styles/config/vocabularies/Suga/accept.txtto include "SQLAlchemy" on its own line.Would you like me to generate a script or shell command to verify and update the Vale vocabulary file?
docs/guides/build-platform.mdx (1)
46-48: Fix hyphenation: "application specific" → "application-specific".When used as a compound modifier before a noun, "specific" should be hyphenated.
-- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application specific resources, such as services, databases, buckets, and entrypoints +- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application-specific resources, such as services, databases, buckets, and entrypointsdocs/develop/overview.mdx (1)
108-108: Minor phrasing clarity: "look to" → "look at".While "look to" is acceptable, "look at" is more direct and aligns with the sentence structure.
- Cloud provider like AWS provide many container and compute runtime options including EC2, ECS and Fargate, Lambda, EKS, and more. The list gets longer as you look to other cloud providers. + Cloud provider like AWS provide many container and compute runtime options including EC2, ECS and Fargate, Lambda, EKS, and more. The list gets longer as you look at other cloud providers.docs/foundations/overview.mdx (1)
68-68: Fix hyphenation: "provision specific" → "provision-specific".When used as a compound modifier before "cloud resources," the phrase should be hyphenated.
-[Plugins](/foundations/plugins) are the lowest-level building blocks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: +[Plugins](/foundations/plugins) are the lowest-level building blocks - reusable Terraform modules that provision provision-specific cloud resources. Each plugin contains:docs/develop/services.mdx (1)
87-90: Simplify phrasing and add missing comma.Tighten the opening phrase and add a comma for grammatical clarity.
-In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. +To establish HTTP routes, Suga automatically injects a `PORT` environment variable into each service, indicating which port it should listen on.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/develop/access-control/service-to-bucket-access-control.pngis excluded by!**/*.pngdocs/images/develop/app-diagram-example.pngis excluded by!**/*.png
📒 Files selected for processing (35)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/deploy/aws.mdx(1 hunks)docs/deploy/azure.mdx(1 hunks)docs/deploy/environment-management.mdx(1 hunks)docs/deploy/gcp.mdx(1 hunks)docs/deploy/overview.mdx(1 hunks)docs/deploy/terraform-configuration.mdx(1 hunks)docs/develop/access-control.mdx(1 hunks)docs/develop/buckets.mdx(1 hunks)docs/develop/databases.mdx(1 hunks)docs/develop/entrypoints.mdx(1 hunks)docs/develop/overview.mdx(1 hunks)docs/develop/services.mdx(1 hunks)docs/develop/suga-client.mdx(1 hunks)docs/docs.json(3 hunks)docs/faq.mdx(1 hunks)docs/foundations/deployment.mdx(1 hunks)docs/foundations/infrastructure-generation.mdx(1 hunks)docs/foundations/local-development.mdx(1 hunks)docs/foundations/overview.mdx(1 hunks)docs/foundations/platforms.mdx(2 hunks)docs/foundations/plugins.mdx(1 hunks)docs/foundations/projects.mdx(1 hunks)docs/guides/build-platform.mdx(4 hunks)docs/guides/plugin-development.mdx(4 hunks)docs/guides/static-website-hosting.mdx(1 hunks)docs/quickstart.mdx(1 hunks)docs/sdks/go/client.mdx(1 hunks)docs/sdks/go/databases.mdx(1 hunks)docs/sdks/node/client.mdx(1 hunks)docs/sdks/node/databases.mdx(1 hunks)docs/sdks/python/client.mdx(1 hunks)docs/sdks/python/databases.mdx(1 hunks)docs/support.mdx(1 hunks)docs/why-suga.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/sdks/go/databases.mdx
🚧 Files skipped from review as they are similar to previous changes (16)
- docs/deploy/azure.mdx
- docs/sdks/go/client.mdx
- docs/deploy/gcp.mdx
- docs/support.mdx
- docs/deploy/environment-management.mdx
- docs/deploy/overview.mdx
- docs/foundations/platforms.mdx
- docs/deploy/terraform-configuration.mdx
- docs/deploy/aws.mdx
- docs/develop/access-control.mdx
- docs/develop/entrypoints.mdx
- docs/guides/plugin-development.mdx
- docs/foundations/projects.mdx
- docs/sdks/python/client.mdx
- docs/why-suga.mdx
- docs/sdks/node/databases.mdx
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
📚 Learning: 2025-09-22T21:56:58.994Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.994Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
Applied to files:
docs/quickstart.mdxdocs/docs.jsondocs/guides/build-platform.mdx
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/quickstart.mdxdocs/foundations/deployment.mdxdocs/foundations/local-development.mdxdocs/foundations/overview.mdxdocs/foundations/infrastructure-generation.mdxdocs/guides/static-website-hosting.mdxdocs/develop/overview.mdxdocs/faq.mdx
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/quickstart.mdxdocs/faq.mdx
📚 Learning: 2025-09-23T23:36:19.429Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 74
File: cli/internal/simulation/simulation.go:85-85
Timestamp: 2025-09-23T23:36:19.429Z
Learning: In the Suga CLI, there are two different contexts for SugaIntro Dashboard output: 1) Simulation server (simulation.go) where Dashboard was correctly removed because it was non-functional, and 2) Development WebSocket server (suga.go) where Dashboard URL is valid and needed for syncing with the dashboard using team slug and port parameters.
Applied to files:
docs/foundations/local-development.mdx
📚 Learning: 2025-08-27T03:55:50.432Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:25-34
Timestamp: 2025-08-27T03:55:50.432Z
Learning: In the Suga project, the default directory for CDKTF synthesized output is `terraform/`, not `cdktf.out/`. The directory structure is terraform/stacks/<stack_name>/ containing the generated Terraform configurations.
Applied to files:
docs/foundations/infrastructure-generation.mdx
📚 Learning: 2025-11-11T07:44:40.142Z
Learnt from: tjholm
Repo: nitrictech/suga PR: 147
File: docs/develop/databases.mdx:28-28
Timestamp: 2025-11-11T07:44:40.142Z
Learning: In Suga, "service" is a countable noun. A Suga application is composed of one or more "services", so phrases like "a service" or "grant a service access" are grammatically correct.
Applied to files:
docs/develop/databases.mdxdocs/develop/services.mdx
🪛 LanguageTool
docs/foundations/deployment.mdx
[style] ~170-~170: Consider shortening or rephrasing this to strengthen your wording.
Context: ...### Updating Your Application When you make changes to your project: 1. **Rebuild Terraform:*...
(MAKE_CHANGES)
docs/foundations/overview.mdx
[uncategorized] ~68-~68: When ‘provision-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...locks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: ...
(SPECIFIC_HYPHEN)
docs/foundations/infrastructure-generation.mdx
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...The suga build command orchestrates a multi-step process: <Step title="Load P...
(EN_COMPOUNDS_MULTI_STEP)
docs/guides/static-website-hosting.mdx
[misspelling] ~99-~99: This word is normally spelled as one.
Context: ...i-Page Applications Deploy traditional multi-page websites: ```yaml buckets: website: ...
(EN_COMPOUNDS_MULTI_PAGE)
docs/develop/databases.mdx
[grammar] ~28-~28: Uncountable nouns are usually not used with an indefinite article. Use simply “service access”.
Context: ... and Connection Strings When you grant a service access to a database, Suga automatically injec...
(A_UNCOUNTABLE)
[uncategorized] ~72-~72: Possible missing comma found.
Context: ... env_var_key: ORDERS_DATABASE_URL ``` Now the api service receives three separa...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/develop/services.mdx
[style] ~88-~88: Consider a more concise word here.
Context: ...e" ``` #### PORT environment variable In order to establish HTTP routes/requests Suga wil...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~89-~89: Possible missing comma found.
Context: ...able In order to establish HTTP routes/requests Suga will automatically inject a PORT...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/.vale/styles/config/vocabularies/Suga/accept.txt
[duplication] ~287-~287: Possible typo: you repeated a word.
Context: ...ars todo href lang nav prev next toc uv Monorepo monorepo Minio Prisma SQLAlchemy datasource sqla...
(ENGLISH_WORD_REPEAT_RULE)
docs/develop/overview.mdx
[uncategorized] ~108-~108: The preposition ‘at’ seems more likely in this position.
Context: ... more. The list gets longer as you look to other cloud providers. The same is tru...
(AI_HYDRA_LEO_REPLACE_TO_AT)
docs/faq.mdx
[uncategorized] ~38-~38: Possible missing preposition found.
Context: ...dd-suga) guide. ### Do I need to learn Terraform? No, but understanding Terraform basic...
(AI_HYDRA_LEO_MISSING_TO)
[typographical] ~87-~87: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...oes deployment take? First deployment: 5-15 minutes (Terraform provisioning cloud r...
(HYPHEN_TO_EN)
[typographical] ~88-~88: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...isioning cloud resources) Code updates: 1-5 minutes (depends on service type and cl...
(HYPHEN_TO_EN)
[uncategorized] ~128-~128: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...icial platforms 4. Extend Suga through [open source contributions](https://github.com/nitri...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/foundations/plugins.mdx
[grammar] ~160-~160: The word ‘reference’ is a noun or an adjective. A verb or adverb is missing or misspelled here, or maybe a comma is missing.
Context: ...expose outputs that other resources can reference: ```hcl title="Lambda plugin outputs" ...
(PRP_MD_NN)
docs/guides/build-platform.mdx
[uncategorized] ~47-~47: When ‘application-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... Templates that define how to provision application specific resources, such as services, databases,...
(SPECIFIC_HYPHEN)
🔇 Additional comments (14)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)
287-306: Vocabulary additions align well with new documentation.The 20 new terms support the expanded documentation topics: Prisma/SQLAlchemy/Minio for databases, Pulumi/SREs/DevOps for infrastructure, and uv/debugpy/dlv/pgx/sqlx/pgxpool for SDK/tooling. No duplicates detected within the new entries. The static analysis hint about duplication is a false positive—the existing vocabulary intentionally includes case variants (e.g., stdout appears twice on lines 88–89).
docs/foundations/plugins.mdx (1)
1-279: Comprehensive and well-structured plugin documentation.Clear explanations of plugin architecture, types, configuration, and usage patterns. Examples, tables, and navigation cards support learning at each section.
docs/quickstart.mdx (1)
378-379: Navigation links correctly updated.Paths updated to reflect new Foundations reorganization.
docs/sdks/node/client.mdx (1)
1-39: LGTM.Clear introduction to Node.js client initialization with appropriate links to storage and database SDKs.
docs/develop/buckets.mdx (1)
1-164: Clear and comprehensive bucket documentation.Multi-language examples, access control patterns, and local development guidance are well-presented.
docs/foundations/infrastructure-generation.mdx (1)
1-198: Excellent infrastructure generation guide.Clear explanation of the build process with appropriate Step components and practical examples. The static analysis flag on "multi-step" is a false positive—it's correct as a compound adjective.
docs/develop/databases.mdx (1)
1-280: Comprehensive database documentation.Multi-language examples, connection string injection, multiple database patterns, and ORM compatibility guidance are all well-covered. The grammar concerns flagged by static analysis are clarified in learnings (service is countable in Suga).
docs/guides/static-website-hosting.mdx (1)
1-335: Well-structured guide with practical examples.The guide effectively covers static site hosting patterns, build integration for multiple frameworks, and environment variable handling. Examples are clear and actionable.
docs/develop/suga-client.mdx (1)
1-250: Excellent explanation of generated client benefits and usage.The multi-language examples and clear comparison with cloud-specific SDKs effectively communicate the portability advantages. Cloud abstraction concepts are well-articulated.
docs/foundations/local-development.mdx (1)
1-349: Comprehensive local development guide with practical examples.Clear coverage of emulated resources, debugging workflows, and realistic limitations. The monorepo-style organization and step-by-step guidance make this accessible for developers.
docs/docs.json (4)
63-73: Guides section additions look correct.New guide entries for "static-website-hosting" and "terraform-backend-config" fit logically within the existing guides structure.
123-148: SDK language pages follow consistent pattern.All three language groups (Python, Node.js, Go) have identical structure: main page + client + storage + databases. This consistency improves navigation predictability.
211-220: Redirects are complete.The git diff confirms only
/projectsand/platformswere moved to/foundations/—both already have redirects defined in docs.json. Other top-level pages (faq, quickstart, support, why-suga) were newly added or modified, not relocated. No additional redirects needed.
22-35: Missing MDX file referenced in docs.jsonThe "develop/environment-variables" page is referenced in the Develop group but the file
docs/develop/environment-variables.mdxdoes not exist. Either create this file or remove the reference from docs.json to prevent broken navigation links.⛔ Skipped due to learnings
Learnt from: jyecusch Repo: nitrictech/suga PR: 78 File: docs/docs.json:24-27 Timestamp: 2025-09-22T21:56:58.994Z Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.Learnt from: davemooreuws Repo: nitrictech/suga PR: 29 File: docs/guides/terraform-backend-config.mdx:0-0 Timestamp: 2025-08-28T06:12:17.266Z Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
jyecusch
force-pushed
the
docs/refine-structure
branch
from
c126825 to
d4ce0ae
Compare
tjholm
left a comment
tjholm
left a comment
There was a problem hiding this comment.
Reviewing on my phone so can't select multiple lines but this section on updating code seems a bit inaccurate (manual push to ecr followed by a terraform apply)
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/develop/services.mdx (1)
87-96: Simplify opening phrase for clarity.Line 89's "In order to establish" is verbose. Consider: "To establish HTTP routes/requests, Suga will automatically inject a
PORTenv var..."The comma addition addresses the missing punctuation before the independent clause.
Apply this diff to improve conciseness:
#### PORT environment variable -In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. +To establish HTTP routes/requests, Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on.docs/faq.mdx (2)
87-88: Use en-dashes for time ranges.Replace hyphens with en-dashes for proper typographic formatting:
-First deployment: 5-15 minutes (Terraform provisioning cloud resources) -Code updates: 1-5 minutes (depends on service type and cloud provider) +First deployment: 5–15 minutes (Terraform provisioning cloud resources) +Code updates: 1–5 minutes (depends on service type and cloud provider)
128-128: Hyphenate compound adjective.Use hyphen when "open source" modifies the following noun:
-4. Extend Suga through [open source contributions](https://github.com/nitrictech/suga) +4. Extend Suga through [open-source contributions](https://github.com/nitrictech/suga)docs/guides/build-platform.mdx (1)
46-48: Add hyphen to compound modifier.Line 47 should use "application-specific" (with hyphen) when used as a modifier:
-- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application specific resources, such as services, databases, buckets, and entrypoints +- **[Resource Blueprints](/foundations/platforms#resource-blueprints)** - Templates that define how to provision application-specific resources, such as services, databases, buckets, and entrypointsdocs/foundations/overview.mdx (1)
66-74: Add hyphen to compound modifier.Line 68 should use "provision-specific" (with hyphen) when used as a modifier before "cloud resources":
-[Plugins](/foundations/plugins) are the lowest-level building blocks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: +[Plugins](/foundations/plugins) are the lowest-level building blocks - reusable Terraform modules that provision-specific cloud resources. Each plugin contains:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/develop/access-control/service-to-bucket-access-control.pngis excluded by!**/*.pngdocs/images/develop/app-diagram-example.pngis excluded by!**/*.png
📒 Files selected for processing (35)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/deploy/aws.mdx(1 hunks)docs/deploy/azure.mdx(1 hunks)docs/deploy/environment-management.mdx(1 hunks)docs/deploy/gcp.mdx(1 hunks)docs/deploy/overview.mdx(1 hunks)docs/deploy/terraform-configuration.mdx(1 hunks)docs/develop/access-control.mdx(1 hunks)docs/develop/buckets.mdx(1 hunks)docs/develop/databases.mdx(1 hunks)docs/develop/entrypoints.mdx(1 hunks)docs/develop/overview.mdx(1 hunks)docs/develop/services.mdx(1 hunks)docs/develop/suga-client.mdx(1 hunks)docs/docs.json(3 hunks)docs/faq.mdx(1 hunks)docs/foundations/deployment.mdx(1 hunks)docs/foundations/infrastructure-generation.mdx(1 hunks)docs/foundations/local-development.mdx(1 hunks)docs/foundations/overview.mdx(1 hunks)docs/foundations/platforms.mdx(2 hunks)docs/foundations/plugins.mdx(1 hunks)docs/foundations/projects.mdx(1 hunks)docs/guides/build-platform.mdx(4 hunks)docs/guides/plugin-development.mdx(4 hunks)docs/guides/static-website-hosting.mdx(1 hunks)docs/quickstart.mdx(1 hunks)docs/sdks/go/client.mdx(1 hunks)docs/sdks/go/databases.mdx(1 hunks)docs/sdks/node/client.mdx(1 hunks)docs/sdks/node/databases.mdx(1 hunks)docs/sdks/python/client.mdx(1 hunks)docs/sdks/python/databases.mdx(1 hunks)docs/support.mdx(1 hunks)docs/why-suga.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/deploy/environment-management.mdx
- docs/why-suga.mdx
- docs/foundations/local-development.mdx
🚧 Files skipped from review as they are similar to previous changes (16)
- docs/develop/entrypoints.mdx
- docs/foundations/platforms.mdx
- docs/sdks/go/client.mdx
- docs/sdks/node/client.mdx
- docs/deploy/azure.mdx
- docs/develop/access-control.mdx
- docs/guides/plugin-development.mdx
- docs/develop/buckets.mdx
- docs/quickstart.mdx
- docs/sdks/python/client.mdx
- docs/develop/suga-client.mdx
- docs/deploy/aws.mdx
- docs/deploy/gcp.mdx
- docs/sdks/python/databases.mdx
- docs/deploy/terraform-configuration.mdx
- docs/sdks/node/databases.mdx
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/guides/static-website-hosting.mdxdocs/deploy/overview.mdxdocs/develop/overview.mdxdocs/faq.mdxdocs/foundations/infrastructure-generation.mdxdocs/foundations/overview.mdx
📚 Learning: 2025-09-22T21:56:58.994Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.994Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
Applied to files:
docs/docs.json
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/deploy/overview.mdxdocs/faq.mdx
📚 Learning: 2025-11-11T07:44:40.142Z
Learnt from: tjholm
Repo: nitrictech/suga PR: 147
File: docs/develop/databases.mdx:28-28
Timestamp: 2025-11-11T07:44:40.142Z
Learning: In Suga, "service" is a countable noun. A Suga application is composed of one or more "services", so phrases like "a service" or "grant a service access" are grammatically correct.
Applied to files:
docs/develop/databases.mdxdocs/develop/services.mdx
📚 Learning: 2025-08-27T03:55:50.432Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:25-34
Timestamp: 2025-08-27T03:55:50.432Z
Learning: In the Suga project, the default directory for CDKTF synthesized output is `terraform/`, not `cdktf.out/`. The directory structure is terraform/stacks/<stack_name>/ containing the generated Terraform configurations.
Applied to files:
docs/foundations/infrastructure-generation.mdx
🪛 LanguageTool
docs/guides/static-website-hosting.mdx
[misspelling] ~99-~99: This word is normally spelled as one.
Context: ...i-Page Applications Deploy traditional multi-page websites: ```yaml buckets: website: ...
(EN_COMPOUNDS_MULTI_PAGE)
docs/foundations/plugins.mdx
[grammar] ~160-~160: The word ‘reference’ is a noun or an adjective. A verb or adverb is missing or misspelled here, or maybe a comma is missing.
Context: ...expose outputs that other resources can reference: ```hcl title="Lambda plugin outputs" ...
(PRP_MD_NN)
docs/.vale/styles/config/vocabularies/Suga/accept.txt
[duplication] ~287-~287: Possible typo: you repeated a word.
Context: ...ars todo href lang nav prev next toc uv Monorepo monorepo Minio Prisma SQLAlchemy datasource sqla...
(ENGLISH_WORD_REPEAT_RULE)
docs/develop/databases.mdx
[grammar] ~28-~28: Uncountable nouns are usually not used with an indefinite article. Use simply “service access”.
Context: ... and Connection Strings When you grant a service access to a database, Suga automatically injec...
(A_UNCOUNTABLE)
[uncategorized] ~72-~72: Possible missing comma found.
Context: ... env_var_key: ORDERS_DATABASE_URL ``` Now the api service receives three separa...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/develop/overview.mdx
[uncategorized] ~108-~108: The preposition ‘at’ seems more likely in this position.
Context: ... more. The list gets longer as you look to other cloud providers. The same is tru...
(AI_HYDRA_LEO_REPLACE_TO_AT)
docs/develop/services.mdx
[style] ~88-~88: Consider a more concise word here.
Context: ...e" ``` #### PORT environment variable In order to establish HTTP routes/requests Suga wil...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~89-~89: Possible missing comma found.
Context: ...able In order to establish HTTP routes/requests Suga will automatically inject a PORT...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/faq.mdx
[uncategorized] ~38-~38: Possible missing preposition found.
Context: ...dd-suga) guide. ### Do I need to learn Terraform? No, but understanding Terraform basic...
(AI_HYDRA_LEO_MISSING_TO)
[typographical] ~87-~87: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...oes deployment take? First deployment: 5-15 minutes (Terraform provisioning cloud r...
(HYPHEN_TO_EN)
[typographical] ~88-~88: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...isioning cloud resources) Code updates: 1-5 minutes (depends on service type and cl...
(HYPHEN_TO_EN)
[uncategorized] ~128-~128: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...icial platforms 4. Extend Suga through [open source contributions](https://github.com/nitri...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/foundations/deployment.mdx
[style] ~170-~170: Consider shortening or rephrasing this to strengthen your wording.
Context: ...### Updating Your Application When you make changes to your project: 1. **Rebuild Terraform:*...
(MAKE_CHANGES)
docs/foundations/infrastructure-generation.mdx
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...The suga build command orchestrates a multi-step process: <Step title="Load P...
(EN_COMPOUNDS_MULTI_STEP)
docs/foundations/overview.mdx
[uncategorized] ~68-~68: When ‘provision-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...locks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: ...
(SPECIFIC_HYPHEN)
docs/guides/build-platform.mdx
[uncategorized] ~47-~47: When ‘application-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... Templates that define how to provision application specific resources, such as services, databases,...
(SPECIFIC_HYPHEN)
🔇 Additional comments (16)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)
287-306: Terms align well with documentation expansion.The new vocabulary entries correctly support the PR's documentation additions: deployment strategies (Pulumi, DevOps), ORMs and databases (SQLAlchemy, Prisma, pgx, sqlx), utilities (uv, Minio, debugpy, dlv), and architectural concepts (Monorepo, Reusability, SREs). The case-variant pairs (Monorepo/monorepo, SQLAlchemy/sqlalchemy) follow the existing pattern in the file and are necessary for Vale's spell checking.
docs/foundations/infrastructure-generation.mdx (1)
1-217: Content looks solid.The infrastructure generation workflow is clearly explained with appropriate examples. Mintlify components are used correctly per learnings. Internal navigation links reference the foundations structure consistently.
docs/foundations/plugins.mdx (1)
1-279: Comprehensive plugin documentation.Well-structured explanation of Suga's plugin architecture with clear examples and official plugin library tables. Navigation links are properly integrated.
docs/develop/databases.mdx (1)
1-280: Clear database documentation.Well-structured overview with appropriate language examples. Proper integration with language-specific SDK documentation and related guides. Per learnings, grammar on line 28 is correct.
docs/develop/services.mdx (1)
1-225: Services documentation is comprehensive.Excellent coverage of configuration, working directories, monorepo patterns, and access control. Examples are clear and relatable.
docs/foundations/projects.mdx (1)
1-248: Navigation paths correctly updated.Link references now properly point to
/foundations/platformspath, aligning with the new documentation structure reorganization.docs/support.mdx (1)
1-89: Support page is well-structured.Clear guidance on documentation, support channels, enterprise offerings, and security reporting. All contact information is consistent and properly formatted.
docs/sdks/go/databases.mdx (1)
1-69: Vale whitelist verified—Go packages are properly configured.The Go package names (
pgx,sqlx,pgxpool) have been successfully added to./docs/.vale/styles/config/vocabularies/Suga/accept.txt. The documentation can proceed without Vale spelling false positives.docs/faq.mdx (1)
20-26: Azure support status is accurately documented; optional wording clarification remains a developer choice.The codebase contains no Azure platform implementation or directories, confirming the learnings that Azure is not officially supported. The current docs wording "Coming soon" is factually reasonable but admittedly vague. Whether to explicitly state "planned but unavailable" or move it to a separate "Planned" section is a documentation preference, not a correctness issue. The change is entirely optional.
docs/guides/static-website-hosting.mdx (1)
1-335: Document structure and content are clear and comprehensive.The guide provides practical examples for multiple frameworks and covers essential topics (build process integration, custom domains, environment variables, local development). All cross-references to
/develop/,/foundations/, and/guides/pages align with the updated navigation structure.docs/develop/overview.mdx (1)
1-198: Previous review feedback has been properly addressed.Line 71 correctly uses "bidirectional" (not hyphenated), and line 104 properly uses a semicolon before "however". The document is well-organized with good YAML examples and clear resource descriptions.
docs/guides/build-platform.mdx (1)
6-6: Path updates are consistent with new Foundations structure.All references to
/platformsand/projectshave been correctly updated to/foundations/platformsand/foundations/projectsrespectively, aligning with the navigation restructuring indocs/docs.json.Also applies to: 13-13, 46-47, 151-151, 409-409
docs/foundations/deployment.mdx (1)
1-414: Comprehensive deployment guide with clear instructions.The document effectively covers the deployment lifecycle, management patterns, multi-environment strategies, and best practices. Previous review feedback regarding punctuation (line 285) has been resolved. Examples and command sequences are accurate and practical.
docs/foundations/overview.mdx (1)
1-298: Architecture overview is clear and well-structured.The three-layer architecture (Projects, Platforms, Plugins) is presented effectively with the Mermaid diagram and supporting explanations. Key concepts, design principles, and the Suga workflow section provide excellent context for new users. The Separation of Concerns table and multiple code examples reinforce the mental model.
docs/docs.json (2)
25-58: New navigation structure effectively organizes expanded documentation.The addition of "Foundations" (renamed from "Core Concepts"), "Develop", and "Deploy" groups provides clear separation of concerns and improves discoverability. Page listings align with new documentation files being added across the PR.
211-220: Redirects provide backward compatibility for path reorganization.The redirects from
/projects→/foundations/projectsand/platforms→/foundations/platformsmaintain backward compatibility as the documentation structure evolves. Ensure that destination pages are correctly configured.
jyecusch
force-pushed
the
docs/refine-structure
branch
from
d4ce0ae to
1c9624a
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
docs/develop/services.mdx (1)
88-89: Simplify phrasing and add missing comma.Line 88-89 can be more concise and needs proper punctuation for the independent clause.
- In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. + To establish HTTP routes/requests, Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on.docs/faq.mdx (2)
87-88: Use en-dashes for time ranges per typographic conventions.Time ranges should use en-dashes instead of hyphens:
- First deployment: 5-15 minutes (Terraform provisioning cloud resources) - Code updates: 1-5 minutes (depends on service type and cloud provider) + First deployment: 5–15 minutes (Terraform provisioning cloud resources) + Code updates: 1–5 minutes (depends on service type and cloud provider)
128-128: Hyphenate compound adjective."Open source" used as a compound adjective modifying "contributions" should be hyphenated:
- 4. Extend Suga through [open source contributions](https://github.com/nitrictech/suga) + 4. Extend Suga through [open-source contributions](https://github.com/nitrictech/suga)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/develop/access-control/service-to-bucket-access-control.pngis excluded by!**/*.pngdocs/images/develop/app-diagram-example.pngis excluded by!**/*.png
📒 Files selected for processing (35)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/deploy/aws.mdx(1 hunks)docs/deploy/azure.mdx(1 hunks)docs/deploy/environment-management.mdx(1 hunks)docs/deploy/gcp.mdx(1 hunks)docs/deploy/overview.mdx(1 hunks)docs/deploy/terraform-configuration.mdx(1 hunks)docs/develop/access-control.mdx(1 hunks)docs/develop/buckets.mdx(1 hunks)docs/develop/databases.mdx(1 hunks)docs/develop/entrypoints.mdx(1 hunks)docs/develop/overview.mdx(1 hunks)docs/develop/services.mdx(1 hunks)docs/develop/suga-client.mdx(1 hunks)docs/docs.json(3 hunks)docs/faq.mdx(1 hunks)docs/foundations/deployment.mdx(1 hunks)docs/foundations/infrastructure-generation.mdx(1 hunks)docs/foundations/local-development.mdx(1 hunks)docs/foundations/overview.mdx(1 hunks)docs/foundations/platforms.mdx(2 hunks)docs/foundations/plugins.mdx(1 hunks)docs/foundations/projects.mdx(1 hunks)docs/guides/build-platform.mdx(4 hunks)docs/guides/plugin-development.mdx(4 hunks)docs/guides/static-website-hosting.mdx(1 hunks)docs/quickstart.mdx(1 hunks)docs/sdks/go/client.mdx(1 hunks)docs/sdks/go/databases.mdx(1 hunks)docs/sdks/node/client.mdx(1 hunks)docs/sdks/node/databases.mdx(1 hunks)docs/sdks/python/client.mdx(1 hunks)docs/sdks/python/databases.mdx(1 hunks)docs/support.mdx(1 hunks)docs/why-suga.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/sdks/go/client.mdx
- docs/sdks/python/databases.mdx
- docs/develop/entrypoints.mdx
🚧 Files skipped from review as they are similar to previous changes (18)
- docs/foundations/projects.mdx
- docs/sdks/python/client.mdx
- docs/deploy/azure.mdx
- docs/sdks/node/client.mdx
- docs/support.mdx
- docs/guides/plugin-development.mdx
- docs/quickstart.mdx
- docs/deploy/aws.mdx
- docs/sdks/go/databases.mdx
- docs/deploy/environment-management.mdx
- docs/sdks/node/databases.mdx
- docs/develop/suga-client.mdx
- docs/deploy/overview.mdx
- docs/deploy/terraform-configuration.mdx
- docs/deploy/gcp.mdx
- docs/develop/access-control.mdx
- docs/foundations/platforms.mdx
- docs/foundations/infrastructure-generation.mdx
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/faq.mdxdocs/guides/static-website-hosting.mdxdocs/why-suga.mdxdocs/foundations/local-development.mdxdocs/foundations/overview.mdxdocs/foundations/deployment.mdx
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/faq.mdxdocs/why-suga.mdx
📚 Learning: 2025-11-11T07:44:40.142Z
Learnt from: tjholm
Repo: nitrictech/suga PR: 147
File: docs/develop/databases.mdx:28-28
Timestamp: 2025-11-11T07:44:40.142Z
Learning: In Suga, "service" is a countable noun. A Suga application is composed of one or more "services", so phrases like "a service" or "grant a service access" are grammatically correct.
Applied to files:
docs/develop/services.mdxdocs/develop/databases.mdx
📚 Learning: 2025-09-22T21:56:58.994Z
Learnt from: jyecusch
Repo: nitrictech/suga PR: 78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.994Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
Applied to files:
docs/docs.jsondocs/guides/build-platform.mdx
📚 Learning: 2025-09-23T23:36:19.429Z
Learnt from: davemooreuws
Repo: nitrictech/suga PR: 74
File: cli/internal/simulation/simulation.go:85-85
Timestamp: 2025-09-23T23:36:19.429Z
Learning: In the Suga CLI, there are two different contexts for SugaIntro Dashboard output: 1) Simulation server (simulation.go) where Dashboard was correctly removed because it was non-functional, and 2) Development WebSocket server (suga.go) where Dashboard URL is valid and needed for syncing with the dashboard using team slug and port parameters.
Applied to files:
docs/foundations/local-development.mdx
🪛 LanguageTool
docs/faq.mdx
[grammar] ~128-~128: Use a hyphen to join words.
Context: ...l platforms 4. Extend Suga through [open source contributions](https://github.com...
(QB_NEW_EN_HYPHEN)
docs/guides/static-website-hosting.mdx
[grammar] ~31-~31: Use a hyphen to join words.
Context: ... via HTTPS with automatic SSL ## Single Page Applications (SPAs) Deploy React, ...
(QB_NEW_EN_HYPHEN)
docs/develop/services.mdx
[style] ~88-~88: Consider a more concise word here.
Context: ...e" ``` #### PORT environment variable In order to establish HTTP routes/requests Suga wil...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~89-~89: Possible missing comma found.
Context: ...able In order to establish HTTP routes/requests Suga will automatically inject a PORT...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/.vale/styles/config/vocabularies/Suga/accept.txt
[duplication] ~287-~287: Possible typo: you repeated a word.
Context: ...ars todo href lang nav prev next toc uv Monorepo monorepo Minio Prisma SQLAlchemy datasource sqla...
(ENGLISH_WORD_REPEAT_RULE)
docs/foundations/overview.mdx
[uncategorized] ~68-~68: When ‘provision-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...locks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: ...
(SPECIFIC_HYPHEN)
docs/develop/overview.mdx
[uncategorized] ~108-~108: The preposition ‘at’ seems more likely in this position.
Context: ... more. The list gets longer as you look to other cloud providers. The same is tru...
(AI_HYDRA_LEO_REPLACE_TO_AT)
docs/develop/databases.mdx
[grammar] ~28-~28: Uncountable nouns are usually not used with an indefinite article. Use simply “service access”.
Context: ... and Connection Strings When you grant a service access to a database, Suga automatically injec...
(A_UNCOUNTABLE)
[uncategorized] ~72-~72: Possible missing comma found.
Context: ... env_var_key: ORDERS_DATABASE_URL ``` Now the api service receives three separa...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/foundations/deployment.mdx
[style] ~170-~170: Consider shortening or rephrasing this to strengthen your wording.
Context: ...### Updating Your Application When you make changes to your project: 1. **Rebuild Terraform:*...
(MAKE_CHANGES)
docs/foundations/plugins.mdx
[grammar] ~160-~160: The word ‘reference’ is a noun or an adjective. A verb or adverb is missing or misspelled here, or maybe a comma is missing.
Context: ...expose outputs that other resources can reference: ```hcl title="Lambda plugin outputs" ...
(PRP_MD_NN)
docs/guides/build-platform.mdx
[uncategorized] ~47-~47: When ‘application-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... Templates that define how to provision application specific resources, such as services, databases,...
(SPECIFIC_HYPHEN)
🔇 Additional comments (7)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)
287-307: Vocabulary additions align well with documentation expansion.The new terms (
uv,Monorepo,Prisma,SQLAlchemy,debugpy,dlv,pgx,sqlx,Pulumi,SREs,DevOps,cicd, etc.) are all correctly spelled and directly relevant to the new deployment, infrastructure, and SDK documentation being added. The allowlist will prevent false positives when Vale lints these technical references.docs/guides/build-platform.mdx (1)
6-6: Link migrations look solid.Internal links correctly updated to reflect the new Foundations-based navigation structure (
/foundations/platforms,/foundations/projects). Consistent throughout the file.Also applies to: 13-13, 46-47, 151-151, 409-409
docs/guides/static-website-hosting.mdx (1)
1-335: Excellent new guide with comprehensive coverage.Well-organized documentation covering hosting scenarios (basic sites, SPAs, frontend + backend, multi-page), framework-specific build integration (React, Vue, Angular, Next.js, Svelte), custom domains via Terraform, and environment variables. Examples are clear and actionable. Links use the correct updated path structure.
docs/develop/overview.mdx (1)
1-198: Well-structured resource documentation.Clear explanation of Suga resource types, relationships, naming conventions, configuration patterns, subtypes, and access control. Links to Develop, Foundations, and Deploy sections align with navigation restructuring. Past review comments have been addressed.
docs/foundations/deployment.mdx (1)
1-412: Comprehensive, well-organized deployment guide.Clear step-by-step lifecycle with appropriate warnings about destructive operations. Good coverage of multi-environment strategies, CI/CD integration, and troubleshooting. Proper use of Mintlify components (Steps, Tabs, Cards) and accurate references to provider-specific guides. Past review comments have been addressed.
docs/docs.json (2)
211-220: Redirects ensure backward compatibility.The new
redirectsfield correctly maps old paths (/projects,/platforms) to their new Foundations-based locations. This prevents broken links for users and search engines.
14-79: Navigation restructuring is comprehensive and well-organized.Core Concepts properly renamed to Foundations. New Develop and Deploy groups logically separate concerns. Guides properly expanded with static-website-hosting and terraform-backend-config. SDK documentation appropriately expanded with subpages for each language (client, storage, databases). Structure aligns with PR objectives and new documentation content.
|
@coderabbitai pause |
✅ Actions performedReviews paused. |
jyecusch
force-pushed
the
docs/refine-structure
branch
from
809d3c0 to
9d8c550
Compare
Co-authored-by: David Moore <4121492+davemooreuws@users.noreply.github.com>
|
🎉 This PR is included in version 0.6.3 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
7 participants
Fixes NIT-531