sacco-architecture-evaluation

Architecture Evaluation

Before Proposing Anything

1. Gather facts — Query APIs, read configs, check plans, inspect repo structures. Never assume org plan, runner setup, repo visibility, or existing tooling. Verify with actual data.
2. Map the constraint space — For each candidate approach, evaluate against ALL of:
   • Security: Does it cross a trust boundary? Could a compromised consumer access sensitive resources?
   • Ownership: Who produces this? Who consumes it? Does the producer need to know about consumers?
   • Coupling: Does this create a dependency between teams/repos that shouldn't know about each other?
   • Portability: Is this tied to a specific vendor? What's the switching cost?
   • Existing tooling: Is this a solved problem? Search before building.
3. Present options with trade-offs — Don't propose one solution. Present the evaluated options, state which you recommend and why, then wait for direction.

Decision Process

Problem identified
  → Gather ALL relevant facts (API calls, file reads, web searches)
  → Identify candidate approaches
  → For EACH candidate, evaluate: security | ownership | coupling | portability | switching cost
  → Eliminate candidates that violate hard constraints
  → Present remaining options with trade-offs
  → Wait for direction — do NOT start implementing

Common Pitfalls

• Jumping to implementation before understanding constraints leads to oscillating between solutions.
• Guessing instead of checking — org plan, repo visibility, runner environment, existing infra are all queryable. Check them.
• Reinventing solved problems — Always search for existing tooling first. If you're designing a schema registry, artifact distribution, or config sharing pattern, it probably already exists as a standard tool (OCI/ORAS, package registries, etc.).
• Hardcoding external dependencies — Third-party URLs go offline. Evaluate whether the dependency is on an open standard (OCI, HTTP) or a specific provider.
• Crossing security boundaries as a shortcut — If the clean solution requires crossing a trust boundary, that's a signal you're solving the wrong problem or at the wrong abstraction level.

Portability Checklist

When evaluating any tool or service:

1. Is the underlying protocol/format an open standard?
2. Can we switch providers by changing a URL/config?
3. Does our data/artifact format survive a migration?
4. Are we coupling to a vendor feature or an industry standard?

Open standards (OCI, HTTP, SQL, S3-compatible) are preferred over vendor-specific features (GitHub internal visibility, AWS-only services) unless the vendor feature solves a problem the standard cannot.