Advanced Modeling Path

Optional path for teams that want reviewed intent in Git.

If you just did Quick start, you already have the core workflow. This page is for the next step: using Sruja to maintain reviewed intent with repo.sruja and the sruja-architecture skill.

Tip

Use this later: This is not required for default adoption. Come here only when you want explicit, reviewable architecture modeling.

Step 1: Generate Reviewed Intent ⏱️ 20–30 min

What you'll do: Let AI analyze your code and create repo.sruja

Instructions:

1. Open your project in your AI editor
2. Run this prompt:

Use sruja-architecture. Run `sruja discover --context -r . --format json`,
gather evidence, identify systems and containers,
generate repo.sruja with C4 context and container levels,
then run `sruja lint` and fix until it passes.

3. Wait for AI to ask 2-3 questions
4. Answer the questions (be specific: "Production database is PostgreSQL")
5. Review the generated repo.sruja file

Success check: You have a repo.sruja file that passes sruja lint

What you learned:

• How AI analyzes your codebase
• What questions it asks
• What a valid repo.sruja looks like

Step 2: Understand What Was Generated ⏱️ 15–20 min

What you'll do: Read and understand your AI-generated architecture

Instructions:

1. Open repo.sruja in your editor
2. Read it section by section:
   • person entries = external actors
   • system entries = your major boundaries
   • container entries = deployable units
   • -> lines = relationships
3. Run sruja tree repo.sruja to see structure visually
4. Ask AI to explain:

Read repo.sruja and explain:
1. What systems are defined?
2. How do containers connect?
3. What external actors use this system?

Success check: You can explain your architecture in plain English

What you learned:

• How reviewed intent is expressed
• How to read relationships
• What each component does

Step 3: Validate and Fix Errors ⏱️ 15–20 min

What you'll do: Learn to validate and fix issues with AI help

Instructions:

1. Run sruja lint repo.sruja
2. If you see errors, copy them to clipboard
3. Ask AI:

I got these lint errors. Fix them in repo.sruja:
[paste errors here]

Common errors:

4. Re-run sruja lint until clean

Success check: sruja lint repo.sruja shows "All checks passed"

What you learned:

• How validation works
• Common architecture errors
• How to ask AI to fix issues

Step 4: Make a Specific Change ⏱️ 20–30 min

What you'll do: Direct AI to add or modify something specific

Instructions:

Think of a change you want. Examples:

• Add component: "Add a logging service container"
• Add relationship: "Connect the new logger to all existing containers"
• Modify description: "Update the API container description to say it handles webhooks"

Then ask AI:

Use sruja-architecture. Read repo.sruja and:
[your change here]
Then run sruja lint and fix any errors.

Success check: Your change is added and sruja lint passes

What you learned:

• How to make targeted updates
• To validate after each change
• That iteration is normal (AI can refine it)

Step 5: Export for Your Team ⏱️ 10–15 min

What you'll do: Share reviewed intent with stakeholders when needed

Instructions:

1. Export Markdown:

sruja export markdown repo.sruja > ARCHITECTURE.md

2. Export diagram:

sruja export mermaid repo.sruja > ARCHITECTURE.mmd

3. Open ARCHITECTURE.md and review
4. Open ARCHITECTURE.mmd in Mermaid Live Editor

Success check: You can send ARCHITECTURE.md to your team and they understand it

What you learned:

• Different export formats
• How to share reviewed intent
• That diagrams are output, not the source

Step 6: Detect and Fix Drift ⏱️ 20–30 min

What you'll do: Keep architecture in sync as code changes

Instructions:

1. Make a small change to your actual code

   • Add a new function
   • Rename a file
   • Move a module

2. Run drift detection:

sruja drift -r . --format json

3. Ask AI:

Use sruja-architecture. Here's drift output:
[paste JSON]
Analyze what changed and update repo.sruja to match current code.

4. Review the changes AI made
5. Run sruja lint repo.sruja

Success check: sruja drift shows no issues (or you've addressed them)

What you learned:

• How to detect changes over time
• To let AI update architecture automatically
• That architecture stays in sync with code

Step 7: Explore Patterns with AI ⏱️ 15–20 min

What you'll do: Use AI as an architecture advisor

Instructions:

Pick a pattern and ask AI to explain it:

Monolith:

Use sruja-architecture. Explain the monolith pattern:
When to use it, pros/cons, and show an example in Sruja syntax.

Microservices:

Use sruja-architecture. Explain microservices:
When to split, trade-offs, and generate an example architecture.

Event-driven:

Use sruja-architecture. Show me an event-driven architecture
with Kafka, producers, and consumers. Explain trade-offs.

Success check: You understand different patterns and when to use them

What you learned:

• Architectural patterns
• When each pattern makes sense
• That AI can be your advisor, not just generator

Tips for Success

Before You Spend Time Here

Make sure the core path is already useful for your team:

• sruja start -r .
• sruja drift -r . --structural-only --advisory
• sruja focus -r . --file <path>
• sruja verify-task --profile coding -r .

If that loop is not already helping, do not invest in advanced modeling yet.

Common Mistakes to Avoid

❌ Don't: "Generate full architecture for everything"

✅ Do: Start with context + container levels, add components when needed

❌ Don't: Guess at missing information

✅ Do: Ask targeted questions, list what's unknown

❌ Don't: Skip validation

✅ Do: Always run sruja lint after AI edits

❌ Don't: Model for completeness

✅ Do: Model what evidence supports—minimal is better

What's Next?

Go deeper:

• System Design 101 – Module 1 – Learn architecture concepts
• Skill Reference – What the skill knows

Practice:

• Try different codebases (your own or open-source examples)
• Practice making specific changes
• Compare different patterns with AI

Connect:

• GitHub Discussions – Ask questions, share patterns
• Community – See how others use Sruja

Quick Reference

Remember: You're not learning a language. You're learning how to:

1. Guide AI with clear requests
2. Validate results
3. Iterate and refine
4. Use AI as an advisor

The skill handles the syntax—you handle the thinking.