docs: Add comprehensive documentation for InFoundry architecture and local development#17
Conversation
- Add docs/architecture.md with system architecture overview, component diagrams, data flow documentation, and integration points - Add docs/blueprint.md with complete system design, project structure, component specifications, API contracts, and data schemas - Add docs/runlocally.md with step-by-step local development guide, service setup instructions, and troubleshooting tips - Add orchestrator/kestra_pipelines/README.md documenting all 9 pipeline steps and AI agent capabilities - Add ui/.env.example for environment configuration - Add CHANGELOG.md, ROADMAP.md, and SECURITY.md for project governance - Add GitHub issue templates for bug reports and feature requests
WalkthroughThis PR adds comprehensive documentation and configuration infrastructure to the InFoundry project. It introduces GitHub issue templates, creates project governance files (CHANGELOG, ROADMAP, SECURITY), rewrites architectural and setup documentation, adds environment configuration examples, and makes minor pipeline configuration adjustments to require specific inputs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
🐰 CodeRabbit Review ReminderThis PR will be automatically reviewed by CodeRabbit. Please ensure:
Maintainer approval is required after addressing CodeRabbit feedback. |
|
Hey there! 👋 I'm replying to this latest reminder, but just a heads up - I don't have context of any earlier comments in this thread since they were too long to include. I see this PR adds a bunch of documentation files covering the InFoundry architecture, blueprints, local setup guides, and governance files. Pretty comprehensive stuff! I'll go ahead and review all these documentation changes to make sure everything looks good - checking for accuracy, completeness, broken links, and general best practices. Let me dive into the review now! ✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
orchestrator/kestra_pipelines/07-create-pr.yaml (2)
46-55: PT5M timeout might be too short + failure can leave half-finished branchWith
timeout: PT5M(Line 48), a slightly larger zip or GitHub slowness can kill the task mid-upload, after the branch is created. Consider either (1) bumping timeout, and/or (2) making the script “fail fast” with a clear error if any upload/PR step fails so you don’t end up with a branch full of partial changes.
124-136: Uploading files: text-mode read + ignores nested folders + ignores per-file PUT result
open(filepath, "r")will blow up on non-UTF8 and is the wrong default for base64; use"rb".os.listdir("iac_files")only grabs top-level files; nested modules/dirs in the zip won’t be uploaded.- You don’t check the return of
github_api("PUT", ...), so you can “succeed” even if uploads failed (rate limit / 409 / 422 / existing file, etc.).- files = list(os.listdir("iac_files")) + files = [] + for root, _, filenames in os.walk("iac_files"): + for fn in filenames: + rel = os.path.relpath(os.path.join(root, fn), "iac_files") + files.append(rel) print(f"Extracted files: {files}") ... - for filename in files: - filepath = f"iac_files/{filename}" - with open(filepath, "r") as f: - content = f.read() + for filename in files: + filepath = os.path.join("iac_files", filename) + with open(filepath, "rb") as f: + content = f.read() ... file_data = { "message": f"Add {filename} via InFoundry", - "content": base64.b64encode(content.encode()).decode(), + "content": base64.b64encode(content).decode(), "branch": branch_name } - github_api("PUT", f"/contents/{target_folder}/{filename}", file_data) + resp = github_api("PUT", f"/contents/{target_folder}/{filename}", file_data) + if not resp: + result["status"] = "failed" + result["message"] = f"Failed to upload {filename}" + breakREADME.md (1)
67-73: Docs link likely broken: README still points at removeddocs/kestra-architecture.md
PR summary says that doc was removed/merged, but README still links to it (Line 70). Update the link to the new doc location.
🧹 Nitpick comments (6)
orchestrator/kestra_pipelines/07-create-pr.yaml (1)
23-33: “required: true” but you still default/fallback it in multiple places (can hide misconfig)Right now
target_folder/labelsare required (Line 23-33), and they have defaults in the input definition, and you do??fallbacks again in env (Line 53-55). Pick one “source of truth” so you don’t accidentally accept empty/incorrect values and silently fall back.- TARGET_FOLDER: "{{ inputs.target_folder ?? 'infra' }}" - LABELS: "{{ inputs.labels ?? 'infoundry,infrastructure,terraform' }}" + TARGET_FOLDER: "{{ inputs.target_folder }}" + LABELS: "{{ inputs.labels }}".github/ISSUE_TEMPLATE/feature_request.md (1)
1-20: Solid starter template; optional: add “acceptance criteria” section
Not required, but an “Acceptance criteria / done when” section tends to reduce back-and-forth.docs/runlocally.md (2)
385-385: Minor style note: Compound adjective hyphenation.The section "Full Stack Development Workflow" should be "Full-Stack Development Workflow" when used as a compound adjective before a noun.
244-244: Consider wrapping bare URLs in markdown link syntax for better rendering.A few bare URLs throughout (e.g.,
http://localhost:3000at line 286) might render better if wrapped as[http://localhost:3000](http://localhost:3000)or enclosed in backticks when inline. This is a minor style suggestion, but it improves markdown consistency.Also applies to: 286-286, 417-419, 509-512
docs/BLUEPRINT.md (1)
7-7: Add language specification to code fences for consistency.The project structure fence (line 7) and JSON schema examples (like line 348) should specify a language: use
```textfor the file tree and```jsonfor JSON blocks. This helps with syntax highlighting and consistency across the docs.-\`\`\` +\`\`\`text infoundry/ ├── docs/And similarly for JSON examples:
-\`\`\` +\`\`\`json { "pattern": "serverless|microservices_ecs|kubernetes|event_driven|lift_and_shift",Also applies to: 348-348
docs/architecture.md (1)
13-13: Markdown style: Add language specs to code fences and blank lines around tables.A few style improvements to align with markdown best practices:
Code fences need language spec: Lines 13, 65, and 170 have ASCII diagrams and code blocks without language specifications. Use
```textor```jsonas appropriate.Tables need surrounding blank lines: Lines 47, 112, and other table locations should have blank lines before and after per MD058. Currently missing blank lines.
These are minor style improvements that help with rendering consistency.
Example for the ASCII diagram (line 13):
-\`\`\` +\`\`\`text ┌─────────────────────────────────────────────────────────────────────────────┐ │ InFoundry ArchitectureAnd add blank lines around tables:
**Key Pages:** + | Route | Purpose | |-------|---------| | `/` | Landing page with feature overview | + **Key Components:**Also applies to: 47-47, 65-65, 112-112, 170-170
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
.github/ISSUE_TEMPLATE/bug_report.md(1 hunks).github/ISSUE_TEMPLATE/feature_request.md(1 hunks)CHANGELOG.md(1 hunks)README.md(1 hunks)ROADMAP.md(1 hunks)SECURITY.md(1 hunks)docs/BLUEPRINT.md(1 hunks)docs/architecture.md(1 hunks)docs/kestra-architecture.md(0 hunks)docs/runlocally.md(1 hunks)infoundry-mcp-server/README.md(1 hunks)orchestrator/kestra_pipelines/07-create-pr.yaml(2 hunks)orchestrator/kestra_pipelines/README.md(1 hunks)ui/.env.example(1 hunks)ui/README.md(1 hunks)
💤 Files with no reviewable changes (1)
- docs/kestra-architecture.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.md
⚙️ CodeRabbit configuration file
Do not emphasize these files too much
Files:
ROADMAP.mdorchestrator/kestra_pipelines/README.mdui/README.mdCHANGELOG.mdSECURITY.mddocs/runlocally.mdinfoundry-mcp-server/README.mddocs/architecture.mddocs/BLUEPRINT.mdREADME.md
🪛 LanguageTool
docs/runlocally.md
[uncategorized] ~385-~385: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...nning node tests/test_kestra.js ``` ## Full Stack Development Workflow ### 1. Start All ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/BLUEPRINT.md
[grammar] ~325-~325: Ensure spelling is correct
Context: ... "source": "mock|provided" } ### ArchitecturePlan json { "architecture": { "pattern": "microservices_ecs", "components": ["api_gateway", "ecs_cluster", "alb", "rds"], "topology": "2 services with microservices_ecs pattern on aws", "scaling_strategy": "horizontal_autoscaling", "estimated_cost_tier": "medium", "rationale": "Selected microservices_ecs based on 2 services" }, "inputs": { "service_count": 2, "cloud_provider": "aws" }, "source": "oumi|heuristic" } ### ReactFlow Graph json { "nodes": [ ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
.github/ISSUE_TEMPLATE/bug_report.md
27-27: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
28-28: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
29-29: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
32-32: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
33-33: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
34-34: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
35-35: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
docs/runlocally.md
244-244: Bare URL used
(MD034, no-bare-urls)
286-286: Bare URL used
(MD034, no-bare-urls)
417-417: Bare URL used
(MD034, no-bare-urls)
418-418: Bare URL used
(MD034, no-bare-urls)
419-419: Bare URL used
(MD034, no-bare-urls)
423-423: Bare URL used
(MD034, no-bare-urls)
509-509: Bare URL used
(MD034, no-bare-urls)
510-510: Bare URL used
(MD034, no-bare-urls)
511-511: Bare URL used
(MD034, no-bare-urls)
512-512: Bare URL used
(MD034, no-bare-urls)
517-517: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
524-524: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
533-533: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/architecture.md
13-13: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
47-47: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
65-65: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
112-112: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
170-170: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/BLUEPRINT.md
7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
457-457: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (10)
ui/.env.example (1)
1-12: Nice: safe defaults + no secrets committedThis is exactly what an
.env.exampleshould look like: works locally, and auth values are commented out so nobody “accidentally” commits real creds.ui/README.md (1)
30-42: Env var setup docs match the new.env.example
Copy step + variable list line up with what you actually ship inui/.env.example.README.md (1)
69-70: No action needed—the documentation links are correctly cased.The file
docs/BLUEPRINT.mdactually exists with uppercase casing, matching the reference in line 69 of the README. Similarly,docs/kestra-architecture.mdmatches line 70. Both links will work correctly on Linux and all other systems.Likely an incorrect or invalid review comment.
orchestrator/kestra_pipelines/README.md (1)
16-24: The README is actually fine here — no changes needed.The
ai_summarizeandai_decidetasks are custom task definitions in your05-generate-iac.yamlpipeline, but they use Kestra's built-inAIAgenttask type (io.kestra.plugin.ai.agent.AIAgent), so the README's phrasing "uses Kestra's built-in AI Agent" is accurate. The README doesn't claim those specific task names are built-in—it just says the pipeline tasks use Kestra's AI capabilities, which is correct. No need to call out a plugin or enterprise feature here.infoundry-mcp-server/README.md (1)
35-38: Nice! Clear environment config example.The addition of the
envblock withGITHUB_TOKENis helpful for users setting up Cline integration. This aligns well with the expanded environment documentation throughout the PR.docs/runlocally.md (1)
1-10: Solid local development guide!The expanded setup guide is well-structured and covers all the key components (Oumi, Kestra, Next.js UI, MCP). The prerequisites table and quick start section make it easy to follow.
ROADMAP.md (1)
1-17: LGTM — clean and straightforward roadmap.The 2026 roadmap is clear and includes a good mix of near-term Q1/Q2 priorities and longer-term ideas. The checkpoint format makes it easy to track progress later.
CHANGELOG.md (1)
1-29: Perfect start to project changelog tracking.Following Keep a Changelog conventions right from the start is great for maintainability. The Unreleased section correctly lists the new documentation and governance files being added in this PR.
docs/BLUEPRINT.md (1)
1-50: Excellent system design reference!This blueprint provides clear specifications for each component, with detailed API contracts, data schemas, and examples. The project structure diagram and component table make it easy to navigate the codebase. Really helpful documentation for contributors.
docs/architecture.md (1)
1-31: Really solid architecture overview!The three-layer architecture diagram (UI → Kestra → Oumi) is crystal clear. The detailed breakdown of each component with tech stacks and key files makes it super useful for getting up to speed. Great job explaining the data flow and integration points.
1 participant
Description
This PR adds comprehensive documentation for the InFoundry project, including system architecture overview, detailed blueprint specifications, and a step-by-step guide for running the project locally. It also adds project governance files and GitHub issue templates to improve contribution workflows.
Type of Change
Related Issues
Closes #
Changes Made
docs/architecture.md- Comprehensive system architecture overview with component diagrams, data flows, and integration pointsdocs/blueprint.md- Complete system design including project structure, component specifications, API contracts, and data schemasdocs/runlocally.md- Step-by-step local development guide with service setup instructions and troubleshooting tipsorchestrator/kestra_pipelines/README.md- Documentation for all 9 pipeline steps and AI agent capabilitiesui/.env.example- Environment configuration template for the Next.js UICHANGELOG.md- Project changelog following Keep a Changelog formatROADMAP.md- High-level project roadmap for 2026SECURITY.md- Security policy and vulnerability reporting guidelines.github/ISSUE_TEMPLATE/bug_report.md- Bug report issue template.github/ISSUE_TEMPLATE/feature_request.md- Feature request issue templateREADME.mdwith corrected documentation linksdocs/kestra-architecture.md(content merged into architecture.md)Infrastructure Changes (if applicable)
N/A - Documentation only
Testing
Test Evidence
All documentation files have been reviewed for accuracy and completeness against the actual codebase.
Checklist
CodeRabbit Review
Screenshots (if applicable)
N/A - Documentation changes only
Additional Notes
This documentation overhaul provides:
This PR will be automatically reviewed by CodeRabbit 🐰
Summary by CodeRabbit
Documentation
Configuration
✏️ Tip: You can customize this high-level summary in your review settings.