https://github.com/sruja-ai/sruja
Sruja is a developer-friendly language for defining, visualizing, and validating software architecture. It brings governance to architecture design and supports AI-driven development—helping individuals follow best practices and enabling organizations to standardize systems with consistent policies and standards.
https://github.com/sruja-ai/sruja
adr ai-driven-development architecture architecture-as-code architecture-governance developer-tools diagrams go governance software-architecture system-design validation-engine wasm
Last synced: 16 days ago
JSON representation
Sruja is a developer-friendly language for defining, visualizing, and validating software architecture. It brings governance to architecture design and supports AI-driven development—helping individuals follow best practices and enabling organizations to standardize systems with consistent policies and standards.
- Host: GitHub
- URL: https://github.com/sruja-ai/sruja
- Owner: sruja-ai
- License: apache-2.0
- Created: 2025-11-23T17:17:32.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T15:30:21.000Z (18 days ago)
- Last Synced: 2025-12-22T18:39:10.332Z (18 days ago)
- Topics: adr, ai-driven-development, architecture, architecture-as-code, architecture-governance, developer-tools, diagrams, go, governance, software-architecture, system-design, validation-engine, wasm
- Language: TypeScript
- Homepage: https://sruja.ai/
- Size: 118 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# Sruja
[](https://codecov.io/gh/sruja-ai/sruja)
**Sruja** is a next-generation architecture-as-code language with first-class support for requirements, ADRs, and extensible validation.
> **⚠️ Alpha Release**: Sruja is under active development. APIs may change.
## Documentation
https://sruja.ai
## Features
- 🎯 **Architecture DSL**: Define systems, containers, components, and relations with first-class support for requirements and ADRs
- ✅ **Validation Engine**: Cycle detection, orphan detection, unique IDs, valid references
- 📊 **Multiple Export Formats**: JSON (Sruja extended), LikeC4 DSL (text), and Markdown for integration with other tools
- 🎨 **Code Formatter**: Auto-format your architecture with `sruja fmt`
- 🌳 **Tree View**: Visualize hierarchy with `sruja tree`
- 🔍 **LSP Support**: Language Server Protocol for IDE integration (VS Code extension available)
- 🎨 **Interactive Designer**: Web-based visual designer for creating and editing architecture diagrams
## Project Structure
```
sruja/
├── cmd/
│ └── sruja/ # Main CLI tool
├── pkg/ # Shared Go packages
│ ├── engine/ # Validation engine
│ ├── language/ # Parser, AST, lexer
│ └── export/ # Exporters (JSON, views)
├── apps/ # Frontend applications
│ ├── website/ # Astro website (docs, courses, tutorials)
│ ├── designer/ # Interactive designer application (Sruja Designer)
│ ├── vscode-extension/ # VS Code language support
│ ├── social-publish/ # Social media publishing tools
│ └── storybook/ # Component documentation
├── packages/ # Shared TypeScript packages
│ ├── shared/ # Shared utilities and types
│ ├── ui/ # UI component library
│ ├── layout/ # Layout algorithms for diagrams
│ └── diagram/ # Diagram rendering utilities
└── examples/ # Example .sruja files
```
### Developer Documentation
**Essential Guides:**
- [Contributing Guide](docs/CONTRIBUTING.md) - How to contribute to Sruja
- [First Contribution](docs/FIRST_CONTRIBUTION.md) - Step-by-step guide for your first contribution
- [Development Guide](docs/DEVELOPMENT.md) - Development practices and tooling
- [Architecture Guide](docs/ARCHITECTURE.md) - Code organization and structure
**Content Creation:**
- [Content Contribution Guide](docs/CONTENT_CONTRIBUTION_GUIDE.md) - Creating courses, tutorials, and docs
- [Content Style Guide](docs/CONTENT_STYLE_GUIDE.md) - Writing style and best practices
**Reference:**
- [Language Specification](docs/LANGUAGE_SPECIFICATION.md) - Complete DSL reference
- [Design Philosophy](docs/DESIGN_PHILOSOPHY.md) - Language design principles
## Installation
### Automated Install (Recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/sruja-ai/sruja/main/scripts/install.sh | bash
```
### Manual Download
Download the latest release from [GitHub Releases](https://github.com/sruja-ai/sruja/releases).
### From Source
```bash
go install github.com/sruja-ai/sruja/cmd/sruja@latest
```
## Quick Start
**Create `example.sruja`:**
```sruja
specification {
element person
element system
element container
element database
}
model {
user = person "User" {
description "End user of the application"
}
app = system "My App" {
web = container "Web Server" {
technology "Node.js"
}
db = database "Database" {
technology "PostgreSQL"
}
}
user -> app.web "visits"
app.web -> app.db "reads/writes"
}
```
**Export to different formats:**
```bash
# Export to JSON (Sruja's extended LikeC4 format with metadata)
sruja export json example.sruja
# Export to Markdown documentation
sruja export markdown example.sruja
# Export to LikeC4 DSL (text format, not JSON)
sruja export likec4 example.sruja
# or use the alias:
sruja export c4 example.sruja
```
**Lint your code:**
```bash
sruja lint example.sruja
```
**Format your code:**
```bash
sruja fmt example.sruja
```
**View hierarchy:**
```bash
sruja tree --file example.sruja
```
## Development
### Prerequisites
- **Go >= 1.25** (CI uses `1.25.5`)
- **Node.js >= 18** (CI uses `24` for most workflows)
### Setup
```bash
# Install dependencies
go mod download
# Setup git hooks (recommended)
make setup-hooks
# Build CLI
make build
```
### Git Hooks
A pre-commit hook automatically tests code compilation when you commit changes to the `examples/` directory. This prevents broken code from being committed.
**Setup:**
```bash
make setup-hooks
```
The hook will:
- Test designer examples compile correctly
- Test course code blocks compile correctly
- Test docs code blocks compile correctly
- Block commits if any code fails to compile
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for more details.
## Contributing
We welcome contributions of all sizes — from small doc fixes to core features.
### 🎯 New to Contributing?
**Start here:** [First Contribution Guide](docs/FIRST_CONTRIBUTION.md)
This guide walks you through making your first contribution, even if you're new to the project.
### Quick Links
- 💡 **Contribution Ideas**: [What Can I Contribute?](docs/CONTRIBUTION_IDEAS.md)
- 🐛 **Find Issues**: [Good First Issues](https://github.com/sruja-ai/sruja/labels/good%20first%20issue) (may be limited for new projects)
- 📖 **Full Guide**: [Contribution Guide](docs/CONTRIBUTING.md)
- 💬 **Get Help**: [Discord](https://discord.gg/VNrvHPV5) | [GitHub Discussions](https://github.com/sruja-ai/sruja/discussions)
### Ways to Contribute
**No Code Required:**
- Fix typos in documentation
- Add examples
- Test and report bugs
- Write tutorials or blog posts
**Code Contributions:**
- Fix bugs
- Add features
- Improve tests
- Enhance tooling
### Pull Request Checklist
- Run local checks: `make test`, `make fmt`, `make lint`
- Add/update tests for new behavior
- Keep changes focused and well‑scoped
- Use Conventional Commits (e.g., `feat: …`, `fix: …`, `docs: …`)
Apache 2.0