Documentation

Everything ARC AI Stack Advisor checks, how it scores, and what it does with your data. If a finding surprised you, the rule behind it is on this page.

How the score is calculated

This is an architecture decision-support score describing how well the recommendation matches the constraints you stated. It is not a rating of your organization, and it does not price anything. Where pricing appears, it is a named cost driver, not a quote.

Each dimension starts at 100. Findings deduct a fixed penalty by severity: critical −30, high −18, medium −9, low −4, info −0. Dimension scores are combined as a weighted average. Bands: 80+ strong, 60–79 adequate, 40–59 at risk, below 40 critical.

Dimension	Weight	What it measures
Requirement Fit	3	Starts at 100. Deducts where a stated requirement has no component in the recommended architecture that satisfies it.
Proportionality	3	Starts at 100. Deducts for each component in the recommendation that is not required by a stated constraint. This dimension penalizes over-architecture on purpose.
Constraint Compliance	3	Starts at 100. Deducts where a stated security, compliance, residency or latency constraint conflicts with the recommended pattern.
Team Capability Match	2	Starts at 100. Deducts where the architecture requires a capability the team did not claim, with no stated plan to acquire it.
Cost Transparency	1	Starts at 100. Deducts for each cost driver that cannot be estimated from the information supplied. Low scores here mean 'we cannot tell you what this costs yet', not 'this is expensive'.

What the score is not

A price quote or a budget commitment
A vendor ranking or endorsement
A guarantee that the architecture will meet your SLAs
A substitute for a proof of concept

Rule catalog (v0.2.0)

22 deterministic rules. No network, no model, no randomness — the same input always produces the same findings. Rule ids are permanent; a rule whose meaning changes gets a new id.

fit

SA-FIT-001simplify
Hard requirement stated without a component that would satisfy it
Either add the component that meets the requirement or renegotiate it explicitly. Do not carry an unmet requirement silently into build.
SA-FIT-002govern
No success criterion or definition of done
Write one sentence a skeptic would accept as done. Architectures without an acceptance bar cannot be compared.
SA-FIT-003simplify
Question-answering use case with no named corpus or system of record
Name the corpus or the system of record first. Retrieval and lookup both start from a source, not from a model.
SA-FIT-004simplify
The described work is a lookup or integration, not a model problem
Query the system of record. Add a model only if a later use case genuinely requires interpretation no rule can encode.
SA-FIT-005govern
No named owner for the system after launch
Name the operating role before picking a pattern. An unowned architecture is a deferred incident.

complexity

SA-COMPLEXITY-001simplify
Agent architecture proposed for a retrieval / Q&A problem
Start with retrieval plus a single constrained generation step. Add agency only when a use case genuinely requires multi-step tool use with branching.
SA-COMPLEXITY-002simplify
Fine-tuning proposed before retrieval is exhausted
Exhaust prompting and retrieval first. Fine-tune for format and behavior, not for knowledge that changes.
SA-COMPLEXITY-003simplify
Multi-agent system proposed
Collapse to a single agent or, better, a fixed workflow. Earn the swarm with a failure the simpler shape could not absorb.
SA-COMPLEXITY-004simplify
RAG proposed for structured or tabular lookup
Replace the RAG loop with a query against the system of record. Keep generation off the path until the answer is no longer in a table.
SA-COMPLEXITY-005simplify
Interactive or real-time loop where batch would suffice
Run it as a batch job with an exception queue. Pay for interactivity only when a person is actually waiting.

constraint

SA-CONSTRAINT-001govern
Data residency or compliance constraint stated
Resolve provider and region eligibility before choosing an architecture. This constraint eliminates options; find out which ones now.
SA-CONSTRAINT-002govern
Tight latency requirement against a multi-hop pattern
Budget latency per hop explicitly before committing. If the budget does not fit, the architecture must change, not the measurement.
SA-CONSTRAINT-003keep-human
High-stakes decision with no human review path
Put a named reviewer on the path before any action that commits the organization. The model proposes; a person disposes.
SA-CONSTRAINT-004secure
Regulated or personal data sent to a public model
Keep regulated data inside a boundary you control. A public consumer API is usually eliminated by this constraint, regardless of quality.
SA-CONSTRAINT-005govern
Audit or logging required but not designed
Log prompt, retrieval, tool call and human decision as reconstructable events. An audit requirement without a log is unmet.

capability

SA-CAPABILITY-001simplify
Architecture requires ML capability the team did not claim
Prefer managed services and a narrower first use case. Plan explicitly for how the team acquires evaluation skills — that is the capability gap that matters most.
SA-CAPABILITY-002simplify
Small team relative to the proposed surface
Cut components until the surface matches the team. A smaller architecture that is actually maintained beats a better one that is not.
SA-CAPABILITY-003simplify
Prefer-build with no platform or evaluation practice named
Default to buy for the undifferentiated middle (hosting, eval harness, tracing). Build the domain-specific piece only.
SA-CAPABILITY-004govern
No evaluation practice described for a model-in-the-path system
Collect a small labeled set before writing production prompts. Evaluation is the first engineering work, not the last.

cost

SA-COST-001simplify
Volume or throughput not stated, so cost cannot be sized
Measure or estimate the driver before committing to a budget. Naming an unknown is more useful than pricing an assumption.
SA-COST-002simplify
Always-on or streaming path where batch would be cheaper
Move the work to a scheduled job. Interactive tokens are a cost you should only pay when someone is waiting.
SA-COST-003simplify
Fine-tune or always-on custom model without a volume that would justify it
Do not train or host a custom model until a measured volume makes prompting plus retrieval more expensive. That comparison needs a number you have not supplied.

Architecture catalog

These are the only shapes the advisor is allowed to recommend. They are patterns, not vendors. A recommendation that names a product as a requirement is a defect. Cost drivers are named, never priced.

Rules, lookup, and integration — no model

The work is retrieving a known record, applying a deterministic rule, or connecting two systems. A language model adds cost, latency and an error mode you cannot currently measure.

Use when: Answers already live in a database, CRM, or policy table. Success is exactness, not fluency.

Do not use when: The input is unstructured and the output requires interpretation no rule can encode.

Schema-constrained extraction or classification

A model (or a rules-plus-model hybrid) writes into a schema: labels, fields, routing. Generation of free prose is out of scope.

Use when: Tickets, emails, forms or documents must become structured records. The schema is known.

Do not use when: The user is asking open questions over a corpus, or the output is a long-form draft.

Retrieve, then generate (RAG)

Find the relevant passages first, then generate an answer constrained to those passages. Citation is a product requirement, not a flourish.

Use when: Questions over an internal corpus (policies, handbooks, runbooks) that changes faster than a model can be retrained.

Do not use when: The answers already live in a queryable table, or the task is multi-step tool use rather than question answering.

Single constrained generation call

One model call, structured prompt, structured or tightly formatted output. No retrieval loop, no tools, no agency.

Use when: Rewrite, draft, or summarize a single provided artifact. The source is in the request.

Do not use when: The model would have to 'know' a corpus it was not given, or take actions in other systems.

Batch / offline processing

Run overnight or on a schedule. Write results to a store. Humans review exceptions. No conversational loop.

Use when: Summaries, classifications or extractions over many items, where a user is not waiting on each one.

Do not use when: An interactive assistant, or a latency budget measured in seconds of user wait.

Human-in-the-loop workflow

A model proposes; a named role disposes. The model never takes the action that commits the organization.

Use when: High-stakes, regulated, or irreversible decisions — clinical, legal, credit, employment, safety.

Do not use when: Low-stakes drafts where a wrong answer is cheap to undo and nobody is waiting on a reviewer.

Tool-using agent

A model plans, calls tools, branches, and retries. This is the expensive, nondeterministic option. It is justified only when the use case itself is multi-step tool use.

Use when: The work requires a sequence of tool calls with branching that cannot be written as a fixed workflow.

Do not use when: Question answering over documents, classification, extraction, or a workflow you can draw on a whiteboard.

API

Everything the web UI does is available over HTTP. No key, no account. Please keep it to a few requests a minute — the rate limiter will tell you if you do not.

POST /api/assess
Content-Type: application/json

{
  "text": "your description here (40–40,000 characters)",
  "context": { "industry": "logistics" },
  "useModel": false
}

→ 200 AssessmentResult   (findings, evidence, score, recommendations, blueprint, limitations)
→ 400 { "error": "..." }   input failed validation
→ 429 { "error": "..." }   rate limited

GET /api/rules    the catalog above, as JSON
GET /api/health   { status, version, rulePackVersion, ruleCount }

Data policy

The text you submit is processed in the request and discarded when the response is sent. It is not written to a database, not used for training, and not sent to a model provider unless you explicitly opt in to the optional narrative pass. Errors are logged with the content redacted.

Email is collected only if you ask for a copy of a report. Assessment never requires it. The full policy is in docs/05-data-policy.md.

Everything else

The complete build package — product brief, PRD, architecture, threat model, evaluation plan, runbook — is in the repository. The roadmap is public and the issue tracker is open.