{"id":34674655,"url":"https://github.com/sruja-ai/sruja","last_synced_at":"2026-04-24T05:01:44.201Z","repository":{"id":326422958,"uuid":"1102559480","full_name":"sruja-ai/sruja","owner":"sruja-ai","description":"Context Engineering and Architecture Intelligence for the AI Era. Machine-readable, continuously validated architecture as code for AI-assisted development.","archived":false,"fork":false,"pushed_at":"2026-04-18T12:15:25.000Z","size":158753,"stargazers_count":17,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T14:25:58.587Z","etag":null,"topics":["adr","agent-skills","ai","ai-driven-development","architecture","architecture-as-code","architecture-governance","developer-tools","governance","rust-lang","software-architecture","system-design","wasm"],"latest_commit_sha":null,"homepage":"https://sruja.ai/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sruja-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY-INSIGHTS.yml","support":"docs/SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["koladilip"]}},"created_at":"2025-11-23T17:17:32.000Z","updated_at":"2026-04-18T12:15:14.000Z","dependencies_parsed_at":"2026-02-17T06:14:11.203Z","dependency_job_id":null,"html_url":"https://github.com/sruja-ai/sruja","commit_stats":null,"previous_names":["sruja-ai/sruja"],"tags_count":136,"template":false,"template_full_name":null,"purl":"pkg:github/sruja-ai/sruja","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sruja-ai%2Fsruja","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sruja-ai%2Fsruja/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sruja-ai%2Fsruja/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sruja-ai%2Fsruja/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sruja-ai","download_url":"https://codeload.github.com/sruja-ai/sruja/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sruja-ai%2Fsruja/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32209895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","agent-skills","ai","ai-driven-development","architecture","architecture-as-code","architecture-governance","developer-tools","governance","rust-lang","software-architecture","system-design","wasm"],"created_at":"2025-12-24T20:01:07.368Z","updated_at":"2026-04-24T05:01:44.148Z","avatar_url":"https://github.com/sruja-ai.png","language":"Rust","funding_links":["https://github.com/sponsors/koladilip"],"categories":[],"sub_categories":[],"readme":"# Sruja – Architecture truth + drift detection + AI context\n\n[![Coverage](https://codecov.io/gh/sruja-ai/sruja/branch/main/graph/badge.svg)](https://codecov.io/gh/sruja-ai/sruja)\n\n**Not a diagram language—architecture truth that stays in sync.** Sruja provides evidence-backed context (graph, drift, violations) so changes stay grounded in your real codebase. You validate, version-control, and enforce it; export to Mermaid when you need a diagram. Integrates with AI editors by providing high-quality architecture context.\n\n**Try it in 60 seconds (no AI required):**\n\n```bash\ncurl -fsSL https://sruja.ai/install.sh | bash\nsruja quickstart -r . --generate-baseline\nsruja lint repo.sruja\n```\n\n---\n\n## What is this?\n\n**Problem:** Your code changes, but your architecture diagrams don't. They're in Miro, LucidChart, or old PDFs—drifting from reality.\n\n**Solution:** Sruja uses AI to analyze your codebase and generate architecture as code (`.sruja` files). You validate, version-control, and export it—keeping it always up-to-date.\n\n**How it works:**\n1. Install the CLI and the sruja-architecture skill\n2. In your AI editor, ask the skill to generate architecture from your code (it runs structural analysis under the hood)\n3. Validate with `sruja lint` and export diagrams when you need them\n\n**You don't write `.sruja` files manually.** Your AI does it for you.\n\n---\n\n## Quick Start\n\n### Option A: Deterministic quickstart (recommended for evaluation)\n\n```bash\ncurl -fsSL https://sruja.ai/install.sh | bash\nsruja quickstart -r . --generate-baseline\n```\n\nThis scans your repo, prints an inventory + structural health report, and writes a draft `repo.sruja` baseline you can version-control.\n\n### Option B: Generate and maintain architecture with AI (recommended for ongoing use)\n\nInstall the skill:\n\n```bash\nnpx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture\n```\n\nThis teaches your AI editor (Cursor, Copilot, Claude, etc.) how to generate Sruja architecture. The skill uses structural analysis (discover, sync, drift) under the hood.\n\n**Supported editors:** Cursor, GitHub Copilot, Claude, Continue.dev, and any editor with [skills.sh](https://skills.sh) support.\n\nGenerate architecture with AI:\n\nIn your AI editor, paste this prompt:\n\n```\nUse sruja-architecture. Run `sruja discover --context -r . --format json`,\ngather evidence from my code, ask targeted questions if needed,\ngenerate repo.sruja, then run `sruja lint` and fix until it passes.\n```\n\nYour AI will:\n1. Run discovery (structural analysis) to understand your code\n2. Ask you a few questions if anything is unclear\n3. Generate a `repo.sruja` file\n4. Run `sruja lint` and fix any validation errors so you see **concrete value in the first run** (real errors/warnings and a clean, valid architecture)\n\n### Daily developer loop\n\nUse the friendlier workflow aliases if you want Sruja to feel like a daily repo assistant instead of a long command list:\n\n```bash\n# First-time repo setup\nsruja start -r . --prompt\n\n# Day-to-day review: refresh evidence and see what changed\nsruja daily -r .\n\n# Keep feedback live while you code\nsruja watch -r .\n\n# Quick repo health check\nsruja doctor -r .\n```\n\nAliases:\n- `start` = `init`\n- `daily` = `review`\n- `overview` = `quickstart`\n- `doctor` = `status`\n\n### Validate and export\n\n```bash\n# Check for errors\nsruja lint repo.sruja\n\n# Export a diagram (for docs, presentations, etc.)\nsruja export mermaid repo.sruja \u003e diagram.mmd\n```\n\nYou can open `diagram.mmd` in [Mermaid Live Editor](https://mermaid.live) or use the VS Code extension for preview. **You can export to Mermaid whenever you need a diagram; Sruja’s job is to keep that architecture valid and in sync** (lint, drift, compliance), not to replace Mermaid—it complements it.\n\n---\n\n## Why use Sruja?\n\n| Before Sruja | After Sruja |\n|----------------|--------------|\n| Diagrams drift from code | Architecture always in sync |\n| Manual updates in drawing tools | AI generates from code |\n| Can't validate architecture | Linting catches errors |\n| Hard to see what changed | Version control shows everything |\n| Scattered across tools | Single source of truth |\n\n### Who is this for?\n\n**Developers and Teams:**\n- Keep architecture documentation accurate\n- Catch architectural issues before they cause problems\n- Onboard new team members faster\n\n**Students and Learners:**\n- Understand real-world architecture patterns\n- See how production systems are designed\n- Practice with actual codebases\n\n**Software Architects:**\n- Enforce standards across teams\n- Detect drift automatically\n- Scale architecture governance\n\n---\n\n## Common Questions\n\n**Do I need to learn the Sruja language?**\n\nNo. Your AI writes the `.sruja` files for you. You just need to know what to ask for, which we provide in prompts.\n\n**What if I don't have an AI editor?**\n\nYou can still use the CLI. For evaluation, start with `sruja quickstart -r . --generate-baseline` and `sruja lint repo.sruja`. Once you have a baseline, use `sruja sync -r .` and `sruja drift -r . -a repo.sruja` to keep declared architecture aligned with your code. The skill makes this workflow smoother in AI editors, but the underlying commands work in CI and automation too.\n\n**Can I use this with my existing project?**\n\nYes. Sruja supports many languages out of the box:\n\n| Language | Support Level |\n|----------|--------------|\n| **JavaScript / TypeScript** | Excellent |\n| **Python** | Excellent |\n| **Go** | Excellent |\n| **Rust** | Excellent (native) |\n| **Java** | Good |\n| **C#** | Good |\n| **Ruby** | Good |\n| **PHP** | Good |\n\nOther languages may have partial support. The skill runs discovery for you; it will report what it detects in your codebase.\n\n**How is this different from diagramming tools?**\n\nDiagramming tools (Miro, LucidChart, Visio) are for drawing. Sruja is for defining architecture as code.\n\n**Diagramming tools:**\n- Manual updates required\n- Drifts from reality\n- No validation\n\n**Sruja:**\n- AI generates from code\n- Always in sync\n- Validates structure\n- Version-controlled\n\nYou can still export diagrams from Sruja—just treat diagrams as output, not the source.\n\n**Sruja vs Mermaid**\n\n| | Mermaid | Sruja |\n|---|--------|-------|\n| **Purpose** | Draw diagrams (syntax for charts) | Define architecture as code; validate and keep in sync |\n| **Value** | Diagrams | Single source of truth, lint, drift, compliance, versioned `.sruja` |\n| **Export** | N/A (native format) | Export to Mermaid (and Markdown/JSON) when you need a diagram |\n\nMermaid is an **export target** for Sruja, not a competitor. Use Sruja for grounding, validation, and persistence; use the exported Mermaid for viewing or embedding diagrams.\n\n**What if the AI makes a mistake?**\n\nRun `sruja lint repo.sruja` to catch errors. Tell your AI: \"Fix these lint errors\" and paste the output.\n\n---\n\n## What can I do?\n\n### Generate and maintain architecture (use the skill)\n\nIn your AI editor, use the **sruja-architecture skill**. It runs discovery and drift under the hood. You can also run these yourself for CI or scripting:\n\n```bash\n# Evidence for the skill (or CI)\nsruja discover --context -r . --format json\n\n# Plain-English explanation of what Sruja found and why\nsruja discover --explain -r .\n\n# Validate\nsruja lint repo.sruja\n\n# Drift (when you have a baseline; the skill uses this too)\nsruja drift -r . -a repo.sruja\n```\n\n### Export for documentation\n\n```bash\n# Markdown (readable docs)\nsruja export markdown repo.sruja \u003e ARCHITECTURE.md\n\n# Mermaid (diagrams)\nsruja export mermaid repo.sruja \u003e ARCHITECTURE.mmd\n\n# JSON (machine-readable)\nsruja export json repo.sruja \u003e ARCHITECTURE.json\n```\n\n### Catch Architectural Drift in CI/CD\n\nPrevent architectural decay by running Sruja in your CI/CD pipeline. The `sruja-check` action provides inline Pull Request annotations for any architectural drift.\n\n```yaml\n# .github/workflows/sruja.yml\nname: Sruja Architectural Check\non: [push, pull_request]\n\njobs:\n  sruja:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Sruja Check\n        uses: sruja-ai/sruja-check@v1\n        with:\n          architecture_file: \"repo.sruja\"\n          violations_baseline: \".sruja/violations.baseline.json\"\n```\n\nThis ensures that any new, unmapped component or layer violation is flagged directly on the PR, keeping your architecture documentation and codebase in perfect sync.\n\n---\n\n## Installation\n\n### CLI (required)\n\n**Option A – Install script (recommended):**\n\n```bash\ncurl -fsSL https://sruja.ai/install.sh | bash\n```\n\nDownloads the latest binary from GitHub Releases. Adds to `~/.local/bin` by default.\n\n**Option B – Install via cargo (requires Rust):**\n\n```bash\ncargo install sruja-cli --git https://github.com/sruja-ai/sruja\n```\n\n**Option C – Build from source:**\n\n```bash\ngit clone https://github.com/sruja-ai/sruja.git\ncd sruja\nmake build\n```\n\n**Verify installation:**\n\n```bash\nsruja --version\n```\n\n### AI Skill (recommended but optional)\n\n```bash\nnpx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture\n```\n\n### VS Code Extension (optional)\n\nInstall from [VS Code Marketplace](https://marketplace.visualstudio.com/) for:\n- Syntax highlighting\n- Diagnostics\n- Diagram preview\n- Export commands\n\n---\n\n## Documentation\n\n**Getting Started:**\n\n- [Install as a Skill](docs/INSTALL_AS_SKILL.md) – Editor-specific setup\n- [Getting Started with Skills](docs/GETTING_STARTED_SKILL.md) – Complete workflow guide\n- [Skill Reference](skills/sruja-architecture/SKILL.md) – What the skill does\n\n**Language \u0026 CLI:**\n\n- [Language Specification](docs/LANGUAGE_SPECIFICATION.md) – Complete DSL reference\n- [Run Guide](docs/RUN_GUIDE.md) – CLI commands and examples\n- [Known Limitations](docs/KNOWN_LIMITATIONS.md) – What Sruja can/can't do\n\n**Advanced Topics:**\n\n- [Multi-Repo Federation Setup Guide](docs/FEDERATION_SETUP_GUIDE.md) – Step-by-step federation setup\n- [Multi-Repo Federation](docs/FEDERATION.md) – Technical reference for federation\n- [Design Philosophy](docs/DESIGN_PHILOSOPHY.md) – Why Sruja works this way\n\n---\n\n## Troubleshooting\n\n**\"sruja: command not found\"**\n\nThe CLI isn't on your PATH. Try:\n\n```bash\n# Add to PATH (if using install script)\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Or re-open your terminal\n```\n\n**Skill isn't loading in my editor**\n\n1. Make sure you ran: `npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture`\n2. Check your editor supports [skills.sh](https://skills.sh)\n3. Restart your editor\n\n**AI generates invalid Sruja code**\n\nRun: `sruja lint repo.sruja --format json`\n\nCopy the error output and paste it to your AI with: \"Fix these lint errors.\"\n\n**Discovery doesn't find my components**\n\n- Check your language is supported (see table above)\n- Make sure you're in the correct directory\n- Run `sruja discover --explain -r .` to see what Sruja inferred and where confidence is lower\n- Try: `sruja quickstart -r .` to see what's being detected\n- Open an issue if something obvious is missing\n\n---\n\n## Contributing\n\nWe welcome contributions!\n\n- [Contributing Guide](docs/CONTRIBUTING.md)\n- [Good First Issues](https://github.com/sruja-ai/sruja/labels/good%20first%20issue)\n\n---\n\n## Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!\n\n---\n\n## License\n\nApache 2.0 or MIT (dual-licensed)\n\n---\n\n## Links\n\n- **Website:** https://sruja.ai\n- **GitHub:** https://github.com/sruja-ai/sruja\n- **Discussions:** https://github.com/sruja-ai/sruja/discussions\n- **Roadmap:** [ROADMAP.md](ROADMAP.md)\n- **Contributing:** [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)\n- **Security:** [docs/SECURITY.md](docs/SECURITY.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsruja-ai%2Fsruja","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsruja-ai%2Fsruja","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsruja-ai%2Fsruja/lists"}