# PortaShape Technical Architecture

## Architectural goal

The architecture must support one product loop across many system types without pretending they are identical. The stable center is a typed system graph plus explicit execution contracts. Adapters translate platform-specific behavior into that center; surfaces and workflows project the center for a particular task.

## Logical architecture

```text
┌──────────────────────────────── PORTASHAPE WORKSPACE ────────────────────────────────┐
│ Explore | Shape | Map | Run | Compare | Library                                     │
└───────────────────────────────┬───────────────────────────────────────────────────────┘
                                │ shared selections, commands, views
┌───────────────────────────────▼───────────────────────────────────────────────────────┐
│ Surface & Composition Engine | Runtime Bridge | Relation Editor | Run Console        │
└───────────────────────────────┬───────────────────────────────────────────────────────┘
                                │ typed operations
┌───────────────────────────────▼───────────────────────────────────────────────────────┐
│                 CANONICAL SYSTEM MODEL / GRAPH                                        │
│ elements | values | scopes | authority | relations | provenance | observations        │
└──────────────┬────────────────────┬────────────────────┬───────────────────────────────┘
               │                    │                    │
┌──────────────▼──────┐  ┌──────────▼──────────┐  ┌─────▼──────────────────────────────┐
│ Discovery &        │  │ Transform &          │  │ Policy, Validation & Provenance   │
│ Interpretation     │  │ Execution Runtime    │  │                                   │
└──────────────┬──────┘  └──────────┬──────────┘  └─────┬──────────────────────────────┘
               │                    │                    │
┌──────────────▼────────────────────▼────────────────────▼───────────────────────────────┐
│ Adapters: APIs | DBs | files | repos | design | content | runtime | services          │
└────────────────────────────────────────────────────────────────────────────────────────┘
                                │
┌───────────────────────────────▼───────────────────────────────────────────────────────┐
│ Artifact Store & Library Registry: `.posh`, packages, versions, signatures, reports    │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

## Canonical system model

The system model is an addressable graph with typed nodes and edges. It should support:

- stable identities across snapshots and adapters;
- source-native paths alongside semantic identities;
- current, proposed, transformed, and destination values;
- schema and constraint references;
- settings, options, content, runtime, derived, and secret-reference scopes;
- authority owner and intended writer;
- capabilities such as read, propose, write, invoke, observe, subscribe, or generate;
- provenance, confidence, version, and observation timestamps;
- arbitrary extension namespaces without changing core semantics.

The graph can be backed by a document store, relational model, graph database, in-memory runtime, or combination. The API contract matters more than one storage technology.

## Adapter architecture

An adapter converts source-specific concepts into canonical model elements and operations.

An adapter may implement:

- connection and authentication;
- capability declaration;
- schema discovery;
- value reads and subscriptions;
- controlled writes or commands;
- validation delegation;
- event and job observation;
- source patch or export generation;
- stable identity strategy;
- version and compatibility reporting.

Adapters should be permission-minimal and may be read-only. A connector may expose only a subset of a system.

## Discovery and interpretation

Discovery combines:

- explicit schemas and metadata;
- static analysis;
- runtime observation;
- adapter-provided annotations;
- known semantic vocabularies;
- existing libraries and mapping history;
- user corrections;
- optional AI-assisted classification.

Every inferred fact carries confidence and evidence. Human correction becomes structured metadata that can be reused in later connections.

## Surface engine

The surface engine maps model elements to interactive components.

A control renderer considers:

- value type and representation;
- semantic role;
- constraints and allowed values;
- authority and write capability;
- scope and permissions;
- current and proposed values;
- validation and risk;
- preferred control from a library;
- target runtime and accessibility requirements.

Surface definitions should be declarative and portable. A renderer can target a hosted web UI, embedded panel, development overlay, generated application, desktop shell, or future client.

## Runtime bridge

The runtime bridge connects surface interaction to observed and applied system behavior.

It separates:

- **observation** — current facts from the system;
- **proposal** — a user or workflow’s intended value;
- **preview** — simulated result;
- **commit** — authoritative write or command;
- **settlement** — observed accepted outcome;
- **record** — provenance and run evidence.

This separation prevents a responsive UI from accidentally claiming authority it does not have.

## Relation and transformation engine

Relations form a graph that can be compiled into an execution plan.

The planner must account for:

- dependency order;
- transform input and output typing;
- conditions and lookups;
- defaults and fallbacks;
- direction and reversibility;
- conflicts and priority;
- capabilities and permissions;
- validation before and after stages;
- partial execution and resumability;
- deterministic versus probabilistic transforms;
- loss and unresolved values.

Transform runtimes may include built-in pure operations, sandboxed code, plugins, remote services, asset pipelines, or model-assisted procedures. Trust level and execution environment are explicit.

## Validation and policy architecture

Validation exists at several layers:

1. artifact schema validation;
2. adapter and connection validation;
3. source value validation;
4. transform input/output validation;
5. destination capability validation;
6. domain assertions and policies;
7. runtime or visual verification after execution.

Policies can gate preview, approval, execution, or promotion. Results are attached to elements, mappings, and runs.

## Provenance architecture

Provenance is append-oriented evidence, not an optional log string. A provenance record can link:

- source observations;
- artifact and library versions;
- relation and transform identifiers;
- user or agent decisions;
- approvals;
- execution environment;
- output values;
- validation results;
- later drift.

## Artifact store and library registry

The artifact subsystem provides:

- canonical JSON serialization;
- schema validation and migration;
- content-addressed identities or hashes;
- imports and dependency resolution;
- layered overrides;
- signatures and trust metadata;
- source-control-friendly formatting;
- package manifests;
- local, organization, and public registries;
- compatibility and deprecation information.

## Ownership contracts from the web runtime

The included Alpine.js + htmx material provides an implementation pattern for web surfaces:

- server/database own durable truth;
- URLs own navigable state;
- native controls hold submitted proposals;
- htmx owns requests and targeted server HTML installation;
- Alpine owns disposable local interaction;
- plain JavaScript islands own specialized browser behavior;
- semantic events coordinate boundaries;
- each significant DOM region has one intended writer.

PortaShape should encode these as surface and runtime metadata, not merely document them as developer advice.

## Web-native reference implementation

A practical initial renderer can use:

- server-rendered HTML for canonical projections;
- htmx for requests, targeted replacement, history, and multi-region updates;
- Alpine.js for immediate local state, focus, visibility, and disposable interaction;
- native forms and links for submitted and navigable state;
- semantic browser events for cross-boundary contracts;
- isolated JavaScript islands for complex editors, charts, canvases, or high-frequency interaction.

This architecture aligns with PortaShape’s emphasis on explicit authority, narrow mutation boundaries, progressive complexity, and inspectable operations.

## Extension model

Extension points include:

- adapters;
- semantic vocabularies;
- element kinds;
- control renderers;
- visualizations;
- transforms;
- validators and policies;
- workflow steps;
- exporters and generators;
- artifact namespaces;
- library packages.

Extensions declare compatibility, permissions, trust, and runtime requirements.

## Deployment models

PortaShape should support several deployments without changing the product model:

### Local development

A sidecar or overlay connected to a repository and local runtime.

### Embedded control surface

A PortaShape surface rendered inside an existing product with scoped permissions.

### Hosted workspace

A multi-system collaborative environment with libraries, approvals, runs, and history.

### Generated project tool

A standalone internal application generated from a surface and selected adapters.

### Agent-mediated operation

An agent may inspect, suggest, or execute through the same typed operations and policies as a human. Agent actions must retain identity, evidence, approvals, and limits.

## Non-functional requirements

- deterministic serialization where possible;
- accessible generated controls;
- incremental model loading for large systems;
- clear read/write boundaries;
- schema and adapter version compatibility;
- sandboxed untrusted transforms;
- resumable long-running jobs;
- inspectable event and operation traces;
- testable surface contracts;
- no raw secret requirement in portable artifacts.