3squaredcircles/protega repository overview

⁠3SC Protega

Your Automated Architecture Guardian.

3SC Protega is a polyglot architectural linter that codifies and enforces your software architecture rules directly within your CI/CD pipeline. It consumes a code graph from 3SC Mappa (cartog-data.json) and validates it against a simple, version-controlled policy file (protega-policy.json) that you define.

Protega moves architectural governance from subjective pull request comments and wiki pages into an objective, automated, and enforceable reality. It answers the question: "Is this code change compliant with our established architectural standards?"

Visit: https://docs.3squaredcircles.com⁠ for configuration capabilities.

⁠A Note on the Name

"Protega" is derived from the Latin word prōtegō, which means "to cover, protect, or defend." This name was chosen because the tool acts as a protega, actively protecting the integrity and long-term health of your codebase's architecture.

---

⁠For the Architect & Technical Lead

As a leader responsible for technical vision and quality, you need to ensure your architectural principles are followed long after the initial design meeting. Protega is your automated enforcement mechanism.

Protega answers your critical questions:

• "How can we stop the 'death by a thousand cuts' that slowly erodes our architecture?"
• "How do we prevent new features from introducing undesirable dependencies, like a feature module calling another feature module directly?"
• "How can we end the endless, subjective debates in pull requests about 'good' vs. 'bad' architecture?"
• "How can we automatically enforce our 'Hexagonal Architecture' or 'Clean Architecture' rules?"

⁠Key Business Values:

• Codify Architectural Rules: Transform abstract principles into concrete, machine-readable rules. Define who can talk to whom, what naming conventions are required, and what dependencies are forbidden.
• Automate Governance: The CI/CD pipeline becomes the ultimate arbiter of architectural compliance. Non-compliant code is blocked before it gets merged, not weeks later during a manual review.
• Reduce Technical Debt: By preventing architectural drift at the source, Protega drastically reduces the accumulation of structural technical debt, which is the most expensive to fix.
• Improve Consistency & Maintainability: An enforced architecture leads to a more predictable, consistent, and maintainable codebase, which accelerates onboarding and future development.

---

⁠For the Engineer

As a developer, you want clear, fast, and objective feedback. Protega provides immediate validation of your work against the established architectural rules, right in your pull request.

Protega is the objective referee for your code's structure.

⁠Key Technical Values:

• Fast, Objective Feedback: Stop guessing if your code structure is correct. Get a simple "pass/fail" result in your CI pipeline, with clear error messages pointing to the exact policy that was violated.
• End "Style" Debates: Protega's rules are based on the codified policy file, not on one person's opinion. This eliminates subjective arguments in code reviews, allowing the team to focus on logic and functionality.
• Interactive Policy Builder: The interactive mode launches a powerful local UI that lets you explore your codebase's graph (from Mappa) and visually build and test architectural rules before committing them.
• Clear Guardrails: Protega provides clear, understandable guardrails that help you and your team build software the "right way" from the start.

---

⁠For the Platform Engineer (DevOps, SRE)

As an operator, you need tools that are secure, automatable, and consistent. Protega is a containerized, self-hosted application designed for safe and seamless integration into any CI/CD pipeline.

⁠Execution Modes:

• execute The primary CI mode. It reads the policy file and the Mappa data file, runs the validation, and returns a pass/fail exit code.
• interactive: Starts a local web server to serve the interactive UI for building, testing, and managing the protega-policy.json file.
• serve-docs: Starts a local web server to serve this documentation.

⁠Produced Artifacts

Verifying Image Signatures All published images are signed with Cosign. To verify:

Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/⁠ Download our public key: curl -O https://www.3squaredsquaredcircles.com/keys/3squaredcircles.pub⁠ Verify: cosign verify --key 3squaredcircles.pub 3squaredcircles/protega:latest