README

Architecture Companion — a developer operating system for Laravel architecture, beside the IDE.

Prerequisite (required)

You must install the core package first:

composer require karim-ashraf/lara-architect

lara-architect-ui only works with karim-ashraf/lara-architect ^1.5.
Without core there is no architecture memory, no snapshots, and nothing for the Companion to show.

1. Install lara-architect     ← required first
2. Install lara-architect-ui  ← this package
3. Build & publish UI assets

Product brand: Lara Architect — Architecture Memory and Improvement Platform for Laravel
Composer: karim-ashraf/lara-architect-ui

What this package is

lara-architect-ui does not analyze code.

It is the Architecture Companion: each screen answers one question.

Core discovers.
UI explains.
Developers decide.

Nav	Question
Home	What should I do now?
Issues	What is wrong, where, and why?
Actions	What can Lara Architect do for me?
Knowledge	What does the system remember / believe?
History	What happened over time?
Settings	How is the Companion configured?

karim-ashraf/lara-architect
        |
        |  ArchitectureContextEnvelope · snapshots · reports
        |
        ↓
karim-ashraf/lara-architect-ui   ← Architecture Companion

Dependency direction is one-way: UI → core. Core must never depend on UI.

Owns	Does not own
Rendering · interaction · developer experience	Analyzer · memory truth · events · contracts

Milestone (0.2): Open Architect → Home answers “what next?” in under 10 seconds.

Product direction: docs/PRODUCT_ROADMAP.md · ADR-0009

Open the Companion

/architect
/architect/home
/architect/issues?context=ProductController&context_type=file

Legacy /architect/workspace redirects to Home.

Acceptance (Phase 1)

Open context (/architect/workspace?context=ProductController)
See health
See issues
Understand why (select issue → explanation)
See possible action
Copy context
Preview Fix — decision screen consuming FixProposal only (Apply later)

Requirements

Requirement	Detail
Core (required first)	`karim-ashraf/lara-architect` ^1.5 — install before this package
PHP	^8.2
Laravel	11 / 12 / 13
Node.js	18+ with npm (build Workspace assets once)

Install

1. Core first

composer require karim-ashraf/lara-architect
php artisan vendor:publish --tag=lara-architect-config

2. Then Workspace UI

composer require karim-ashraf/lara-architect-ui

Until Packagist lists this package, add a VCS repository in your app composer.json:

"repositories": [
  { "type": "vcs", "url": "https://github.com/gubakareem/lara-architect-ui" }
]

composer require karim-ashraf/lara-architect-ui:^0.1

3. Build and publish assets

cd vendor/karim-ashraf/lara-architect-ui
npm install && npm run build
php artisan vendor:publish --tag=lara-architect-ui-assets

Local path develop (optional)

Both packages as siblings:

// Laravel app composer.json
"repositories": [
  { "type": "path", "url": "../lara-architect" },
  { "type": "path", "url": "../lara-architect-ui" }
]

composer require karim-ashraf/lara-architect:@dev
composer require karim-ashraf/lara-architect-ui:@dev

Update

composer update karim-ashraf/lara-architect karim-ashraf/lara-architect-ui --prefer-dist
cd vendor/karim-ashraf/lara-architect-ui && npm install && npm run build
php artisan vendor:publish --tag=lara-architect-ui-assets --force

If update fails with would clobber existing tag:

composer clear-cache
# PowerShell
Remove-Item -Recurse -Force vendor\karim-ashraf\lara-architect, vendor\karim-ashraf\lara-architect-ui -ErrorAction SilentlyContinue
# bash: rm -rf vendor/karim-ashraf/lara-architect vendor/karim-ashraf/lara-architect-ui

composer update karim-ashraf/lara-architect karim-ashraf/lara-architect-ui --prefer-dist

Open:

/architect/workspace?context=ProductController&context_type=file

JSON (same snapshot adapters use):

/architect/workspace?context=ProductController&format=json

Architecture

UI (React)
  ↓ consumes (never owns analysis)
WorkspaceSnapshot  ·  GovernanceSnapshot  ·  Learning / Collaboration reports
FixProposal  ·  ControlledChangeResult
  ↓ from
lara-architect (core)

Domain language only: WorkspaceShell, IssueList, IssueDetails, ActionPanel, FixPreviewShell — not Dashboard / Widget.

Phase 2 Preview: React never generates code. Metric = Proposal Understanding Rate (what / why / risk / verification in ~30s).

Dev

npm install
npm run dev    # Vite on :5177

With npm run dev, the Blade view loads the Vite client when assets are unpublished.

Phase 1.5

Workspace Intelligence — breadcrumb, priority issues, impact dimensions, related context, neighborhood map.

Phase 2 — Fix Preview

Decision screen (not a diff editor):

GET /architect/workspace/propose?issue_id=…&context=ProductController

Returns FixProposal JSON (summary, change_set, architecture_impact, status: viewed).

Phase 2.1 — Change Understanding ✅

Milestone: know what changes, where, and how architecture improves — before mutation.

preview/
├── FixPreviewShell.tsx
├── ChangeNavigator.tsx
├── FileChangeList.tsx
├── DiffViewer.tsx              ← comprehension only (not git)
├── ArchitectureImpact.tsx
├── VerificationDetails.tsx
├── StartImprovementButton.tsx  ← no ApplyButton.tsx
└── SessionComplete.tsx

Phase 3 — Controlled Change ✅

Not “Apply Fix”. Architectural event:

Preview → Accept → Prepare → Apply → Verify (gate) → Session

Safe proposals: Start Improvement
Assisted/Design: Apply Later records ProposalReviewed only (no mutation)
Session recorded only after verification passes (storage/architect/sessions/)
ChangeExecution.events is append-only (Replay-ready)

POST /architect/workspace/review
POST /architect/workspace/improve
POST /architect/workspace/confidence

Phase 3.1 — Improvement Confidence ✅

After Session: “Did this improvement help?” → Yes / Not really.

Feeds Improvement Success Rate (storage/architect/metrics/improvement_success.json).

Phase 4 — Architecture Memory ✅

GET /architect/workspace/history?context=ProductController

History panel: recent improvements + chronological Replay. Event stream under storage/architect/events/. Baseline under storage/architect/baseline.json.

Phase 4.1 — Architecture Story ✅

History explains itself: Problem → Decision → Change → Proof → Result (+ period trend). Events carry correlation IDs for Replay chains.

Still postponed: AI · VS Code · GitHub · dashboards.

karim-ashraf / lara-architect-ui

Package info

Security

Statistics