Architecture Insights

Archyl's AI-powered analysis detects potential architectural issues and provides recommendations to improve your system design.

What Insights Does Archyl Detect?

Critical Issues

High Priority

Medium Priority

Low Priority

Running Architecture Analysis

Single Project Analysis

1. Go to the Insights section from the sidebar
2. Select your project
3. Click Analyze
4. Wait for analysis to complete
5. Review findings by severity

Organization-Wide Analysis

To analyze all projects at once:

1. Go to Insights from the main navigation
2. Click Analyze All Projects
3. Review aggregated findings across your organization

Understanding Insights

Each insight includes:

Severity Level

• Critical: Requires immediate attention
• High: Should be addressed soon
• Medium: Consider addressing when possible
• Low: Nice to have improvements

Affected Elements

The insight lists all elements involved, with direct links to view them in the diagram.

Recommendations

Actionable steps to resolve the issue:

Recommendation: Add a caching layer between the API Gateway
and the Database to reduce direct database connections and
improve resilience.

Related Documentation

Links to relevant best practices and architectural patterns.

Managing Insights

Silencing Insights

If an insight is intentional or a false positive:

1. Click on the insight to expand it
2. Click Silence this insight
3. Optionally add a reason
4. The insight will be hidden from the main view

Viewing Silenced Insights

To review silenced insights:

1. Go to the Insights section
2. Toggle Show silenced
3. Review and optionally unsilence items

Bulk Actions

Select multiple insights to:

• Silence all selected
• Assign to team member
• Export as report

Best Practices

Regular Analysis

• Run analysis after major architecture changes
• Include insights review in sprint planning
• Track insight trends over time

Prioritize by Impact

Not all insights need immediate action:

1. Focus on Critical and High severity first
2. Consider business impact when prioritizing
3. Document intentional deviations

Share with Team

• Export insights reports for architecture reviews
• Assign insights to team members
• Track resolution in your project management tool

Common Insights and Solutions

Single Point of Failure

Problem: One service handles all authentication.

Solution:

• Add redundant auth service
• Implement circuit breaker pattern
• Use distributed session storage

High Coupling

Problem: Frontend directly calls 10+ backend services.

Solution:

• Introduce API Gateway
• Implement Backend for Frontend (BFF) pattern
• Use event-driven communication

Circular Dependencies

Problem: Service A depends on B, B depends on C, C depends on A.

Solution:

• Extract shared logic to new service
• Use event-driven architecture
• Refactor to break the cycle

Orphan Elements

Problem: Database with no connections shown.

Solution:

• Add relationships to services that use it
• Remove if no longer used
• Link to documentation explaining usage

Customizing Insight Rules

Every organization has different architecture standards. Archyl lets you customize the rules that generate insights to match your team's requirements.

Accessing Rule Settings

1. Go to the Insights section
2. Click the Rules tab
3. Adjust settings for each rule
4. Click Save to apply changes

When you save changes, Archyl automatically re-analyzes your architecture with the new configuration.

Available Rules

Single Point of Failure (SPOF)

Detects elements with too many incoming dependencies that could cause system-wide failures if they go down.

Raise the threshold if your architecture intentionally centralizes certain concerns. Critical infrastructure like databases receive extra scrutiny regardless of your threshold setting.

High Coupling

Identifies components with excessive connections in either direction.

The incoming threshold catches elements that many other components depend on. The outgoing threshold catches elements that depend on too many other components. Platform teams building shared libraries may want higher thresholds than product teams.

Over-connected Elements

Flags elements with too many total connections (incoming + outgoing combined).

This catches a different problem than high coupling: components that are hard to reason about because they touch too many parts of the system.

Circular Dependencies

Detects dependency cycles where A depends on B, B depends on C, and C depends on A.

Circular dependencies complicate testing, create initialization headaches, and signal unclear boundaries. Most teams leave this enabled.

Orphan Elements

Finds architecture elements with no connections to other components.

Orphan elements might indicate documentation gaps or deprecated services that should be removed.

Security Issues

Detects concerning patterns like external systems with direct database access.

These findings are critical severity and most teams want to know about them immediately.

Missing Documentation

Reports elements without descriptions.

To avoid overwhelming reports on large codebases, documentation checks for components only run if your total component count is below this threshold. Systems and containers are always checked.

Organization-Wide Settings

Insight rules apply across your entire organization, not per-project. This ensures consistent governance standards across all teams and projects.

Resetting to Defaults

Click Reset to defaults in the Rules tab to restore all rules to their original configuration.

Next Steps

• AI-Powered Discovery - Keep architecture up to date
• Documentation - Document architectural decisions
• Export - Export insights reports