Decision-Layer Architecture
Avelin is built around a workforce decision architecture with explicit boundaries:
- shared workforce evidence and references,
- tenant-scoped Customer Grounding,
- decision interpretation,
- stable delivery channels.
REST is the stable integration contract. The current MCP release is a customer-operated stdio adapter over authenticated Runtime routes, so MCP does not own or redefine decision semantics.
Why this matters
Section titled “Why this matters”Each signal family serves a different purpose. An occupational reference is not the same as a market signal; customer policy is not the same as shared evidence. Separating these roles improves explainability.
Architecture flow
Section titled “Architecture flow”
Each endpoint follows the same governed pattern: validate scope, retrieve bounded evidence, apply decision semantics, preserve limitations, and return review-oriented outputs.
Source and grounding boundaries
Section titled “Source and grounding boundaries”Shared sources and tenant sources remain distinct by design. This keeps customer policies from silently overriding shared evidence and shared references from being incorrectly treated as organization-specific.
Customer Grounding expands role context and policy relevance without changing the meaning of shared evidence. A customer rubric is authoritative for that tenant’s workflow; it does not become a general occupation or market fact.
Current evidence boundary
Section titled “Current evidence boundary”The current public product uses request context, the local O*NET 30.3 occupation reference, Avelin market aggregates derived from observed job postings, and tenant-scoped Customer Grounding where authorized. Within the approved U.S./Connecticut Workforce Evidence Pack boundary, it also exposes reviewed OEWS occupation evidence and separate Census QWI industry evidence. These evidence families remain source-specific and are not treated as interchangeable; other geographies, external benchmarks, and roadmap evidence are not implied.
Authority, coverage, and freshness therefore remain source-specific. O*NET provides versioned occupation structure. Market responses expose their aggregation scope, country where supported, counts, percentages, or adjacent time windows. Grounding responses preserve source versions and safe references, but the controlled beta does not provide external connectors or universal freshness/conflict scoring.
Decision layer responsibilities
Section titled “Decision layer responsibilities”Depending on the endpoint, the Decision Layer can expose whether a result is:
- directly supportable,
- weak and uncertain,
- or likely requiring review.
Decision Passport as an Output Projection
Section titled “Decision Passport as an Output Projection”Decision Passport is an optional output projection on the same grounded report endpoint, not a separate service.
For POST /api/v1/grounding/role-intelligence/reports with include_passport=true, Avelin adds a bounded traceable envelope that carries decision identity, evidence references, limits, governance state, and review routing context.
The projection is additive and does not change the historical payload shape when omitted.
Job-intelligence responses express this through confidence, uncertainty, ambiguity, weak-signal, quality, and decision fields. Grounded reports expose evidence and trace references. The Decision Layer explains how to interpret these without assuming that every endpoint returns every signal.
Delivery channels
Section titled “Delivery channels”REST is the stable integration contract for Runtime and platform routes. MCP remains a customer-operated adapter model over the authenticated Runtime API.
Neither channel defines the decision semantics.
Architecture links
Section titled “Architecture links”Current scope
Section titled “Current scope”- Job analysis and classification,
- occupation detail,
- labor-market APIs,
- Customer Grounding,
- decision-support output structure.
The platform is bounded by documented current capabilities and review requirements.