mcpField
A
arch

arch

github.com/alphaonedevDevelopment44 installs
Repository

About arch

arch is an OpenClaw skill for system architecture work, aimed at engineers making design and technology decisions. It creates ADRs, compares trade-offs, recommends stacks, and produces diagrams or structured reports.

Key features

  1. 01Generate Markdown ADRs
  2. 02Compare options using trade-off models
  3. 03Recommend technology stacks
  4. 04Produce system design diagrams
  5. 05Refine designs iteratively

Use cases

  1. 01Document a decision during project kickoff
  2. 02Compare database or architecture options
  3. 03Plan a system refactor or scaling effort

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/alphaonedev/openclaw-graph --skill arch

After installing, type/archin Claude Code to confirm it loaded.

Details

From the project README

arch

Purpose

This skill handles root SE architecture tasks, including system design, creating Architecture Decision Records (ADRs), performing trade-off analyses, and selecting tech stacks. It integrates with OpenClaw's core engine to output structured artifacts like diagrams, documents, or JSON reports.

When to Use

Use this skill when starting a new system design, evaluating architectural decisions, or resolving trade-offs in tech choices. Apply it during project kickoffs, refactoring, or when scaling systems, especially for complex applications involving microservices, cloud infrastructure, or distributed systems.

Key Capabilities

  • Generate ADRs in Markdown format with sections for context, decision, and consequences.
  • Analyze trade-offs using predefined models (e.g., CAP theorem for distributed systems).
  • Recommend tech stacks based on inputs like requirements, constraints, and performance metrics.
  • Produce system design diagrams via integration with tools like PlantUML.
  • Support iterative refinement of designs through feedback loops.

Usage Patterns

Invoke the skill via OpenClaw CLI or API for interactive or scripted workflows. Start with a command to initialize a design session, then chain subcommands for analysis. For example, pipe outputs to other tools for visualization. Always provide inputs as JSON files for consistency. Use environment variables for authentication, like $OPENCLAW_API_KEY, to secure requests.

Common Commands/API

Use the OpenClaw CLI with the arch subcommand. Prefix all commands with openclaw arch.

  • Design a system: openclaw arch design --input design.json --output system.md
    This generates a system design document. The --input flag requires a JSON file with fields like {"requirements": ["scalable"], "components": ["database", "API"]}.

  • Create an ADR: openclaw arch adr --title "Use Microservices" --context "Monolith limitations" --decision "Adopt microservices"
    Example snippet:

    openclaw arch adr --title "Microservices ADR" > adr.md
cat adr.md  # Outputs: # Architecture Decision Record\n## Title: Microservices ADR\n## Context: ...

  • Analyze trade-offs: openclaw arch tradeoff --options "monolith,microservices" --criteria "scalability,cost"
    API endpoint: POST /api/skills/arch/tradeoff with body: {"options": ["monolith"], "criteria": ["cost"]}
    Response: JSON like {"winner": "microservices", "reasons": ["better scalability"]}.

  • Select tech stack: openclaw arch techstack --requirements "high-availability,nodejs" --constraints "budget:low"
    Config format: JSON input e.g., {"requirements": ["REST API"], "constraints": {"budget": 1000}}
    API: POST /api/skills/arch/techstack returns {"recommendations": ["Express.js", "MongoDB"]}.

Always set $OPENCLAW_API_KEY for API calls, e.g., in curl: curl -H "Authorization: Bearer $OPENCLAW_API_KEY" -X POST https://api.openclaw.ai/api/skills/arch/design.

Integration Notes

Integrate with OpenClaw by including the skill in workflows via CLI piping or API chaining. Dependencies: Node.js runtime for local execution. For auth, set $OPENCLAW_API_KEY as an environment variable before running commands. Example integration with Git: Hook into pre-commit to validate designs, e.g., openclaw arch validate --file architecture.md && git commit. Use JSON for inputs/outputs to enable parsing in scripts. Avoid direct file modifications; use --output flags. If using in a CI/CD pipeline, wrap commands in a script like:

export OPENCLAW_API_KEY=your_key
openclaw arch design --input ci-input.json > output.md

Error Handling

Common errors include invalid inputs (e.g., missing JSON fields) or auth failures. Check for HTTP 401 on API calls if $OPENCLAW_API_KEY is unset or invalid—fix by exporting the variable. For CLI, errors like "Invalid flag" return exit code 1; parse with if [ $? -ne 0 ]; then echo "Fix input and retry"; fi. Handle trade-off analysis errors (e.g., unsupported criteria) by catching JSON responses like {"error": "Criterion not found"} and retry with corrected inputs. Always validate JSON schemas before commands using tools like jq:

jq . design.json  # Ensure it's valid JSON
openclaw arch design --input design.json

Concrete Usage Examples

  1. Generate an ADR for a microservices migration: First, prepare a JSON file: {"title": "Microservices Migration", "context": "Current monolith is unscalable"}. Run: openclaw arch adr --input adr-input.json --output migration-adr.md. This produces a Markdown ADR file for version control, e.g., commit it to track decisions.

  2. Analyze trade-offs for database selection: Input options via CLI: openclaw arch tradeoff --options "MongoDB,PostgreSQL" --criteria "flexibility,query-speed". Review the output JSON to decide, then integrate into design: openclaw arch design --input previous-output.json. This workflow helps in selecting PostgreSQL for complex queries based on analysis results.

Graph Relationships

  • Relates to: se-design (for detailed implementation), se-implementation (for code-level integration)
  • Depends on: core-engine (for processing), se-tools (for visualization utilities)
  • Conflicts with: none directly, but avoid overlapping with se-security for access controls

Comments

Markdown supported