Frequently Asked Questions

New to Sruja? Start here.

Installation

Do I need to know programming to use Sruja?

Not really. You need:

• Basic comfort with terminals (running commands)
• A codebase to document (any language)
• An AI editor (Cursor, Copilot, Claude, etc.)

You don't write the .sruja files manually—your AI does it.

What editors work with Sruja?

AI editors with skill support:

• Cursor ✅ (built-in support)
• GitHub Copilot ✅ (requires skills.sh)
• Claude ✅ (requires skills.sh)
• Continue.dev ✅ (requires skills.sh)
• Any editor with skills.sh support

Manual use:

• VS Code with Sruja extension (syntax highlighting, preview)
• Terminal (run commands manually, write .sruja by hand)

What's the difference between the CLI and the skill?

You need both: CLI for validation, skill for generation.

Can I use Sruja without an AI editor?

Yes, but it's more work.

You can:

• Run sruja discover and manually create .sruja files
• Use the VS Code extension for syntax highlighting
• Write .sruja by hand using the language reference

However, AI makes it 10x easier. Consider using Cursor or installing skills.sh for your current editor.

Workflow

How long does it take to generate architecture?

First time: 5-10 minutes

• AI analyzes code
• AI asks 2-3 questions
• AI generates and validates

Updates: 2-5 minutes

• AI reads existing file
• AI makes your change
• AI validates

With practice: Most updates are 1-2 minutes

What information does AI need from me?

Usually just 2-3 questions:

1. System boundaries: "What are the main systems?"
2. External actors: "Who or what calls your system?"
3. Deployment: "How is this deployed?"

The AI gets everything else from your code.

What if I don't know the answer to a question?

That's fine! Tell your AI:

I don't know the answer to "What's the deployment model?"
Please assume [state your best guess or leave as TODO].

The AI can generate a TODO or make reasonable assumptions, which you can refine later.

Files and Syntax

What's the difference between repo.sruja and architecture.sruja?

They're the same thing, just different names.

• repo.sruja – Recommended for new projects
• architecture.sruja – Supported for backward compatibility

Use whichever you like—Sruja detects both.

Where should I put repo.sruja?

Repository root (same folder as package.json, pom.xml, etc.)

Example structure:

my-project/
├── src/
├── package.json
├── README.md
└── repo.sruja          ← Put it here

Can I have multiple .sruja files?

Yes. Common patterns:

• One file per system: user-service.sruja, order-service.sruja
• One per module: auth.sruja, api.sruja, db.sruja
• Nested: arch/repo.sruja, arch/services.sruja

Sruja will detect any .sruja file when you run commands.

Do I need to import from stdlib?

Recommended: yes.

import { * } from 'sruja.ai/stdlib' gives you standard types:

• person, system, container, database, queue
• Without needing to define them manually

You can still define types manually (see Quick Start), but imports save time.

Validation

What does sruja lint check?

Run sruja lint repo.sruja before committing changes.

What if I see errors?

Copy and paste to AI:

Fix these lint errors in repo.sruja:
[paste errors]

Common fixes:

Can I ignore lint errors?

Not recommended. Lint errors indicate real issues:

• Your architecture might not match reality
• Team members might misunderstand the design
• Documentation might be incomplete

Fix errors or add a comment explaining why it's okay.

Using with AI

How specific should I be with prompts?

More specific = better results.

❌ Too vague:

Improve my architecture.

✅ Specific:

Add error handling to the API container.
Update the description to mention rate limiting.

What if AI generates something wrong?

Don't panic. This is normal.

1. Tell AI: "This isn't quite right. Here's what I want: [describe]"
2. Or: "Undo that change. Try again with these constraints: [list]"
3. Or: Make the change yourself, then ask AI to validate

Validation catches mistakes, and iteration is expected.

Can AI handle large codebases?

Yes. Sruja scales:

• Small (10-100 files): Full analysis in seconds
• Medium (100-1000 files): Full analysis in 1-2 minutes
• Large (1000+ files): May take several minutes

AI can handle any size—it just processes more data for larger projects.

Comparison to Other Tools

How is Sruja different from diagramming tools (Miro, LucidChart)?

Think of it this way: Diagrams are like screenshots—great for viewing, but not the source.

How is Sruja different from architecture frameworks (Spring, DDD)?

Sruja doesn't replace frameworks—it documents them.

• Frameworks (Spring, DDD, Clean Architecture) – Guide how to write code
• Sruja – Documents what your code actually does

You can use both: Sruja documents your Spring-based microservices architecture.

AI and Architecture

Why do I need the Sruja skill when I can just ask AI for architecture?

AI proposes; Sruja grounds, validates, and persists.

Without Sruja, AI can suggest architecture, but it's:

• Ungrounded: AI may invent components or dependencies that don't exist in your code
• Ephemeral: You get ad-hoc text or diagrams with no single source of truth

The Sruja skill gives AI:

• Real evidence (from your codebase) to reason about
• Validation (lint, drift) to ensure accuracy
• Persistence (repo.sruja as a first-class artifact in your repo)

Three pillars:

1. Grounding — The skill feeds the model real data (discover, context, graph) so it reasons on what's actually in the codebase, not on guesses. Without Sruja, the model can hallucinate modules and edges.
2. Validation and sync — The skill uses sruja lint (valid DSL), sruja drift (declared vs actual), and intent check. So you get architecture that is valid and stays in sync with code, not a one-off diagram.
3. Persistence and reuse — Architecture lives as repo.sruja in the repo: versionable, exportable, comparable over time. The model without Sruja gives ad-hoc text or Mermaid; with Sruja, the output is a first-class artifact the whole team and CI can use.

Think of it this way: AI is the architect proposing designs. Sruja is the structural engineer providing real data, validating plans, and making sure the blueprint is saved in your repo.

Language Support

What programming languages does Sruja support?

What if my language isn't listed?

Try it! Run:

sruja discover -r . --format json

If you see reasonable output, Sruja can analyze it. If not, please open an issue.

Troubleshooting

"sruja: command not found"

The CLI isn't on your PATH.

Try:

# Check if installed
which sruja

# Add to PATH (if using install script)
export PATH="$HOME/.local/bin:$PATH"

# Or restart your terminal

Skill not loading in my editor

Common causes:

1. Didn't restart editor after installing
2. Editor doesn't support skills.sh
3. Typed wrong skill name

Fixes:

• Restart your editor
• Try: npx skills list to see installed skills
• Check editor has skills.sh support

"Command fails: directory not found"

You're in the wrong folder.

Make sure:

# You should be IN your project
cd your-project

# Not AT the Sruja repo
# ❌ Wrong: cd ~/sruja
# ✅ Right: cd ~/my-project

Discovery shows nothing

Possible causes:

1. No supported files – Empty directory or wrong language
2. Wrong directory – Not in the project root
3. Language limitation – Partial support for that language

Try:

# See what's detected
sruja discover -r . --format json

# Try quickstart for better visibility
sruja quickstart -r .

Best Practices

Start small

✅ Do:

• Get person + system + container levels working first
• Add components only when needed
• Model what evidence supports

❌ Don't:

• Model everything you can think of
• Add components "for completeness"
• Over-complicate simple systems

Validate often

✅ Do:

• Run sruja lint after each AI edit
• Check before committing
• Fix errors before calling it "done"

❌ Don't:

• Skip validation to "save time"
• Commit known errors with a TODO

Iterate with AI

✅ Do:

• Treat first attempt as draft, not final
• Provide feedback: "Good, but add X"
• Ask AI to refine specific parts

❌ Don't:

• Expect perfection on first try
• Give up if it's not exactly right
• Start over from scratch instead of refining

Document decisions

✅ Do:

• Add descriptions to components
• Note why you chose a pattern
• Explain trade-offs

❌ Don't:

• Leave components unlabeled
• Assume everyone knows your intent

Getting Help

Where can I ask questions?

• GitHub Discussions: https://github.com/sruja-ai/sruja/discussions
• Documentation: Getting Started or Beginner Path
• Examples: Examples Gallery

How do I report a bug?

1. Check if it's already reported: https://github.com/sruja-ai/sruja/issues
2. If not, create a new issue with:
   • Steps to reproduce
   • What you expected
   • What actually happened
   • Your environment (OS, editor, language)

How do I contribute?

See Contributing Guide for guidelines.

Quick Command Reference

Key Takeaways

1. You don't learn a language—you guide AI
2. Validation is your friend—run lint often
3. Start minimal—add detail only when needed
4. Iterate—refine with feedback
5. Use AI as advisor—ask about patterns and trade-offs

The skill handles syntax. You handle thinking.