Arvelis

From business problems to working software.

Arvelis is an AI-native engineering experiment for turning an unstructured operational requirement into a validated, reviewable workspace that runs on one generic, metadata-driven application.

It does not generate arbitrary customer code. An AI Architect proposes a constrained WorkspaceDefinition; deterministic validation decides whether that definition is safe to execute; a human then decides whether it actually represents the requested business operation.

This repository demonstrates a product-engineering approach to AI integration: use AI for probabilistic interpretation, but keep executable behavior constrained, inspectable, and under human control.

One engineer. One specification. Under 42 hours. An AI-native operational platform built with deterministic safety boundaries.

Live demo

Open the public product story at arvelis.youneed.dev/about, then choose View live demo to enter the fictional Aurelia Hotel Operations workspace.

The public demo is deterministic and read-only:

• it uses fictional data only;
• a restricted demo account has access only to the intended demo workspace;
• live AI generation, workspace creation/evolution, record mutation, and workflow mutation are blocked;
• private workspaces remain server-side isolated.

The public route and demo provisioning are part of the application, not a screenshot-only mockup. Provision the local demo with php artisan arvelis:seed-public-demo.

Product Preview

Public product story

The public entry explains the requirement-to-runtime path, its deliberate safety boundaries, and how to enter the live demo.

Product overview

The authenticated entry gives an operator a clear starting point: describe a business, open existing workspaces, or follow the product loop.

Describe the operation

The AI Architect accepts a business requirement and makes the validation and human-review boundary clear before any workspace is created.

Browse validated workspaces

The workspace library presents persistent metadata-driven operations and clearly identifies the fictional demo workspace.

Operate through one generic runtime

Aurelia Hotel Operations shows the same runtime interpreting configured modules, records, workflows, calculations, and constraints without a hotel-specific application.

Evolve by reviewed change

Existing workspaces accept a new operational requirement as a bounded proposal; nothing changes until the proposal is validated and explicitly applied.

What Arvelis does

1. A user describes the people, resources, records, processes, and rules of an operation.
2. The AI Architect returns a strict, structured candidate definition.
3. The deterministic validator checks structure, types, relations, workflows, calculations, automations, temporal constraints, and supported runtime contracts.
4. A human reviews the candidate before workspace creation.
5. The generic runtime turns an accepted definition into operational records, forms, lists, workflow actions, notifications, permissions, and calculated values.
6. Existing workspaces can evolve through a separately validated and human-confirmed patch flow.

Architecture

flowchart TD
    A[Business requirement] --> B[AI Architect]
    B --> C[Candidate WorkspaceDefinition]
    C --> D[Deterministic validator]
    D -->|rejected| E[Structured findings / one controlled repair]
    E --> B
    D -->|accepted| F[Human semantic review]
    F -->|confirmed| G[Workspace creator]
    G --> H[Metadata-driven runtime]

Loading

flowchart TD
    A[Existing WorkspaceDefinition] --> C[AI Evolution Proposal]
    B[New business requirement] --> C
    C --> D[Candidate WorkspacePatch]
    D --> E[Patch validation]
    E --> F[Human confirmation]
    F --> G[Transactional apply]
    G --> H[Updated generic runtime]

Loading

Core architecture

• Frontend: React 18, TypeScript, Inertia, Tailwind CSS, Vite.
• Backend: Laravel 12 and PHP 8.3.
• Data: PostgreSQL in the production-style deployment, with metadata definitions and generic workspace records.
• AI boundary: OpenAI Responses API behind a dedicated Architect provider abstraction and strict structured output.
• Runtime: one metadata-driven operational engine—not separate hotel, rental, garage, or furniture applications.

WorkspaceDefinition and generic runtime

The supported declarative model includes entities, typed fields, explicit relations, views, workflows, calculations, automations, notifications, dashboards, roles, permissions, and temporal exclusion constraints.

Current field types are text, textarea, integer, decimal, money, boolean, date, datetime, select, and relation. The runtime supplies typed CRUD, relation handling, workflow transitions, constrained calculations, automation dispatch, server-side authorization, workspace isolation, and metadata-driven UI.

The important constraint is deliberate: generated metadata is interpreted by a controlled runtime. Arvelis does not execute AI-produced PHP, JavaScript, SQL, shell commands, arbitrary formulas, or dotted relationship traversal.

Safety model

AI output is untrusted input, not executable authority.

• Structured output is constrained by the WorkspaceDefinition contract.
• Definitions receive deterministic reference, type, relation-path, workflow, calculation, and automation validation before they can be created.
• A failed initial candidate can receive at most one controlled repair.
• Unsupported behavior must be disclosed as a limitation instead of being represented by a plausible but false approximation.
• Workspace writes, workflow transitions, permissions, and temporal constraints are enforced server-side.
• Human approval remains explicit and authoritative.

This leaves three distinct correctness boundaries:

1. AI Architect — probabilistic requirement interpretation.
2. Deterministic validator — executable structural, type, relation, and runtime safety.
3. Human semantic review — whether the proposal is meaningful and complete for the business.

Deterministic validity is not semantic correctness.

Workspace evolution

Arvelis evolves a workspace with a WorkspacePatch, rather than blindly replacing its definition:

Existing definition + change request → candidate patch → deterministic validation → review → transactional apply

The patch path preserves the current definition context, has stale-definition and double-apply protection, is authorization and workspace scoped, persists proposal evidence, and applies only after human confirmation. Unsafe destructive changes are rejected rather than silently applied.

Temporal capabilities

The generic temporal layer supports:

• trusted application-clock current_date and current_datetime values;
• typed date/date-time comparisons: before, after, on_or_before, on_or_after, equals, and not_equals;
• constrained days_between and hours_between calculations;
• server-enforced temporal exclusions for one related resource and one start/end interval.

Temporal exclusions use half-open [start, end) intervals: a record ending at 10:00 and another beginning at 10:00 do not conflict. Checks are scoped to the workspace and entity, exclude the current record during updates, and run on the server before persistence.

Temporal conditions evaluate when an existing automation trigger runs. Arvelis does not yet include a scheduler or clock-driven autonomous actions.

Blind testing and model quality

The project used unseen Bulgarian-language business scenarios as boundary tests, without product-specific runtime branches.

Blind Test #1 — custom furniture operations

The final proposal passed deterministic validation after two attempts and received a semantic pass with an explicit deferred capability. It credibly modeled customers, orders, materials, order materials, tasks, an order lifecycle, and a Ready-state follow-up. It disclosed that a true stock-shortage calculation needed a cross-record numeric dependency unavailable in the then-safe calculation contract. The proposal was useful, but it did not claim full stock-comparison execution. See the evidence record.

Blind Test #2 — equipment rental operations

The gpt-5-mini baseline was closed — safely rejected. It modeled important domain concepts but produced invalid workflow, relation-action, and temporal approximations. Deterministic validation blocked workspace creation before runtime execution. That result is preserved as evidence, not rewritten as a success. See the evidence record.

The rental test exposed generic temporal capability gaps; the later temporal layer above was implemented as a generic runtime capability, not rental-specific logic.

Controlled model-quality comparison

A controlled engineering comparison reused the same rental requirement, schema, validator, runtime, and structured-output path:

Run	Result
gpt-5-mini baseline	Repair required; candidate remained invalid and was deterministically rejected.
gpt-5.4-mini, medium reasoning	Inconclusive: the provider output was truncated before a candidate was available.
gpt-5.4-mini, low reasoning	One attempt, no repair, complete structured output, deterministic pass, and eligible for human confirmation.

The stronger low-reasoning run materially improved fidelity and honestly deferred unsupported behavior, but human review still found partial fulfillment only. This is not a scientific benchmark or an autonomy claim. The preferred future Architect configuration is gpt-5.4-mini with low reasoning effort; configuration remains environment-driven. See the full comparison.

Engineering decisions

The design deliberately favors truthful constrained behavior over feature theatre:

• explicit requirements are constraints, not suggestions;
• safe degradation prefers explicit capability deferral over fabricated approximation;
• workflow transitions own workflow state;
• relation existence alone does not establish a legal action path;
• unavailable runtime values must not be faked with literals;
• generic primitives beat domain-specific branches;
• human approval is not bypassed by AI confidence.

The decision record is in DECISIONS.md.

Testing and verification

The suite covers validator behavior, calculations, workflows, automations, workspace isolation, authorization, runtime CRUD, temporal exclusion, evolution, public demo restrictions, and generation/repair flows with mocked providers. No normal automated test consumes provider tokens.

Run the current verification commands:

php artisan test
./vendor/bin/pint --test
composer validate --no-check-publish
npm run build
php artisan migrate:status

See BUILD_LOG.md for phase evidence and recorded results.

Known v1 boundaries

• No arbitrary generated code, executable formulas, SQL, shell actions, or unrestricted dotted traversal.
• No recurring scheduler or clock-driven autonomous trigger.
• No external calendar, accounting, billing, or messaging integration.
• Complex related-record mutations remain deliberately constrained.
• No independent semantic AI Reviewer yet; human semantic approval remains required.
• No claim of universal business-process coverage or autonomous correctness.

Experiment metrics

The recorded experiment ran from 2026-09-04T20:53:37+02:00 to 2026-09-06T14:42:18+02:00: 41 hours, 48 minutes, 41 seconds elapsed (under 42 hours). This is elapsed experiment time, not an active-engineering-time claim.

Verified generation evidence is recorded in the blind-test documents. For example, the furniture blind test used two attempts and 14,999 provider tokens; the controlled gpt-5.4-mini B2 comparison completed in one attempt using 6,602 total tokens.

Local development

Requirements: PHP 8.3+, Composer, Node.js, npm, and a configured PostgreSQL database for a production-like setup.

composer install
npm install
cp .env.example .env
php artisan key:generate
# Configure database values in .env, then:
php artisan migrate
npm run dev
php artisan serve

To build frontend assets for production:

npm run build

To provision only the fictional constrained public demo:

php artisan arvelis:seed-public-demo

Keep API credentials in environment configuration. Do not commit .env files or production secrets.

Production deployment

The production-style deployment uses Laravel behind Nginx and PHP-FPM with HTTPS. It exposes a small /health endpoint, uses environment separation, applies migrations through Laravel, and keeps debug mode disabled in production. Public demo entry creates a restricted session and redirects to the seeded Aurelia workspace; it does not expose demo credentials or invoke the Architect provider.

Repository structure

app/Domain/AiArchitect/            provider abstraction and generation pipeline
app/Domain/WorkspaceDefinitions/   contract, schema, validation, semantic guidance
app/Domain/Runtime/                generic workspace interpreter and temporal enforcement
app/Http/Controllers/              authenticated, proposal, runtime, and demo endpoints
resources/js/                      React/Inertia product UI and runtime screens
tests/                             unit and feature coverage
docs/                              blind-test evidence and engineering case study

Future work

Focused next candidates—not current v1 claims—include an independent semantic AI Reviewer, safely declared related-record mutation, scheduler/time-driven automations, richer dashboards, workspace-specific timezones, and carefully chosen external integrations.

For the longer build narrative, production QA lessons, and a reusable portfolio summary, read docs/CASE_STUDY.md.