docs: platform development guide

[raksiv]

Guide for building Suga platforms with serverless and stateful deployment strategies using Lambda, Fargate, and supporting infrastructure.

Closes: NIT-247

[coderabbitai]

📝 Walkthrough

Walkthrough

Inserted "guides/build-platform" into the Guides group in docs/docs.json and added docs/guides/build-platform.mdx, a Platform Development Guide describing a two‑phase platform build: Phase 1 — serverless (CloudFront → Lambda → S3/Neon) with blueprints, variables, reference syntax, revision/testing workflow; Phase 2 — stateful (ALB → Fargate in VPC) with shared VPC, security groups, internal ALB, Fargate blueprint wiring, and multi‑blueprint guidance. Also added accepted vocabulary terms (serverless, subnets, runtimes, rollout) to docs/.vale/styles/config/vocabularies/Suga/accept.txt. No functional code changes.

Suggested reviewers

• tjholm
• HomelessDinosaur
• sean-nitric
• raksiv
• jyecusch

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly and concisely summarizes the addition of a platform development guide and aligns directly with the main changes in the PR.
Description Check	✅ Passed	The description succinctly describes the new guide on building Suga platforms and references the relevant issue, directly matching the content of this changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b59226d and 8ad9add.

⛔ Files ignored due to path filters (9)

• docs/images/build-platform/add-iam-role.png is excluded by !**/*.png
• docs/images/build-platform/aws-fargate-arch.png is excluded by !**/*.png
• docs/images/build-platform/aws-lambda-arch.png is excluded by !**/*.png
• docs/images/build-platform/create-platform.png is excluded by !**/*.png
• docs/images/build-platform/edit-platform.png is excluded by !**/*.png
• docs/images/build-platform/platform-details.png is excluded by !**/*.png
• docs/images/build-platform/test-multiple-services.png is excluded by !**/*.png
• docs/images/build-platform/test-platform-subtype.png is excluded by !**/*.png
• docs/images/build-platform/test-platform.png is excluded by !**/*.png

📒 Files selected for processing (2)

• docs/docs.json (1 hunks)
• docs/guides/build-platform.mdx (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: Test Docs

docs/guides/build-platform.mdx

[error] 8-8: [Vale.Spelling] Did you really mean 'Serverless'?

---

[error] 16-16: [Vale.Spelling] Did you really mean 'Serverless'?

---

[error] 78-78: [Vale.Spelling] Did you really mean 'serverless'?

---

[error] 150-150: [Vale.Spelling] Did you really mean 'serverless'?

---

[error] 198-198: [Vale.Spelling] Did you really mean 'subnets'?

---

[error] 198-198: [Vale.Spelling] Did you really mean 'serverless'?

---

[error] 349-349: [Vale.Spelling] Did you really mean 'runtimes'?

---

[error] 349-349: [Vale.Spelling] Did you really mean 'serverless'?

---

[error] 431-431: [Vale.Spelling] Did you really mean 'rollout'?

🪛 GitHub Check: Spell Check with Vale

docs/guides/build-platform.mdx

[failure] 431-431:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'rollout'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'rollout'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 431, "column": 43}}}, "severity": "ERROR"}

---

[failure] 349-349:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 349, "column": 276}}}, "severity": "ERROR"}

---

[failure] 349-349:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'runtimes'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'runtimes'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 349, "column": 242}}}, "severity": "ERROR"}

---

[failure] 198-198:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 198, "column": 151}}}, "severity": "ERROR"}

---

[failure] 198-198:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'subnets'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'subnets'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 198, "column": 84}}}, "severity": "ERROR"}

---

[failure] 150-150:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 150, "column": 102}}}, "severity": "ERROR"}

---

[failure] 78-78:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 78, "column": 70}}}, "severity": "ERROR"}

---

[failure] 16-16:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 16, "column": 19}}}, "severity": "ERROR"}

---

[failure] 8-8:
[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Serverless'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Serverless'?", "location": {"path": "docs/guides/build-platform.mdx", "range": {"start": {"line": 8, "column": 12}}}, "severity": "ERROR"}

[davemooreuws]

In the future, we should have a platforms group of pages that splits some of this stuff out to make each part more discoverable.

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

docs/guides/build-platform.mdx (1)

8-8: Vale spelling for technical terms

If CI still flags “Serverless/serverless/subnets/runtimes/rollout,” keep the accept-list updated or rephrase.

#!/bin/bash
# Verify the accepted vocabulary contains required terms
fd accept.txt | xargs -I{} sh -c 'echo "== {} =="; cat "{}"'
rg -n "\b(Serverless|serverless|subnets|runtimes|rollout)\b" docs/guides/build-platform.mdx

Also applies to: 16-16, 78-78, 150-150, 198-198, 349-349, 431-431

🧹 Nitpick comments (2)

docs/guides/build-platform.mdx (2)

229-241: lb_listener_port is defined but unused by the Load Balancer

You define lb_listener_port and use it only in the SG rule. If the LB/listener needs this, wire it there; otherwise remove the var to avoid confusion.

Proposed adjustments (pick one):

• Wire into LB plugin (if supported):

 # Load balancer properties
 internal: false
 subnets: ${infra.aws_vpc.public_subnets}
 security_groups: ["${infra.aws_vpc.default_security_group_id}"]
+listener_port: ${var.lb_listener_port}

• Or remove the variable if not used elsewhere:

- lb_listener_port:
-   type: number
-   description: ""
-   default: 80
-   nullable: false

Also applies to: 306-312, 325-340

---

111-118: Fill in variable descriptions

Empty descriptions reduce clarity in the editor. Add concise, actionable descriptions (e.g., “Neon project ID where databases will be created”).

 neon_project_id:
   type: string
-  description: ""
+  description: "Neon project ID used for creating databases"
   default: <your-neon-project-id>
   nullable: false

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0e7b929 and 0356d52.

⛔ Files ignored due to path filters (2)

• docs/images/build-platform/aws-fargate-arch.png is excluded by !**/*.png
• docs/images/build-platform/aws-lambda-arch.png is excluded by !**/*.png

📒 Files selected for processing (1)

• docs/guides/build-platform.mdx (1 hunks)

🔇 Additional comments (3)

docs/guides/build-platform.mdx (3)

300-312: Confirm support for CloudFront prefix list by name
Verify that the security-group-rule plugin’s schema and implementation accept prefix_list_names and correctly resolve “com.amazonaws.global.cloudfront.origin-facing” by name (some AWS APIs require prefix list IDs).

---

371-379: Confirm loadbalancer/fargate plugin behavior for listeners
I didn’t find explicit listener or target-group properties in the plugin code; please verify whether they’re auto-inferred or document the required fields (e.g. lb_listener_port, target group settings) in the guide.

---

6-6: All internal links and anchors are correct. Routes /platforms (#plugins, #variables, #resource-blueprints), /projects, /quickstart, and /cli/build resolve to existing pages and headings.

[nitric-bot]

🎉 This PR is included in version 0.1.25 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀