> ## Documentation Index
> Fetch the complete documentation index at: https://arclux-os.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprint — Repository War Universe

> Visi strategis ARCLUX sebagai universe yang digerakkan oleh repository

# 🚀 ARCLUX — Repository War Universe

> Repository adalah sumber kebenaran. ARCLUX adalah universe yang \
> memvisualisasikan, mensimulasikan, dan memberi kehidupan pada repository.

**Blueprint strategis — dibaca dengan izin** · Lihat
[docs/blueprint/BLUEPRINT\_LICENSE.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/BLUEPRINT_LICENSE.md)
sebelum menggunakan. Draf iterasi 1.

***

## 0. Kompas Strategis

**Satu kalimat visi:**

> ARCLUX menjadi universe tanpa batas tempat setiap software repository
> menjadi source of truth bagi entitas virtual (kapal) yang dapat
> divisualisasikan, dikembangkan, ditransfer, dirusak, diperbaiki, dan
> berjejak sejarah — dengan engine code-intelligence sebagai mesin di
> baliknya, dan ARCLUX sebagai *canvas*, bukan konten.

**3 prinsip non-negotiable:**

1. **Repo user = source of truth.** Kapal dibangun user di repo mereka
   (`.arclux/`), BUKAN di repo ARCLUX.
2. **ARCLUX = canvas + mesin.** ARCLUX membangun universe/aturan/engine;
   konten (kapal, senjata, system) 100% karya user.
3. **Serangan tidak merusak code asli.** Damage hanya menyentuh layer
   `.arclux/` / world-state; repo project aman. **"Repair = commit"**
   (bukan tombol).
4. **Combat: visual boleh cinematic, hasil harus deterministic + tervalidasi.**
   Client boleh menggambar perang; client tidak boleh menentukan kebenarannya.
   *"Users create the machines. ARCLUX defines the physics. The server verifies
   reality."*

**Struktur 3 lapis:**

```
ARCLUX CORE (code intelligence — SUDAH ADA / OP)
   ├─ Parser / Indexer / Graph / Detector / Impact / Security
   ├─ SDK / MCP / CLI / DSL          (sudah live di npm)
   ├─ .arclux/ layer                 (BELUM ADA — titik baru)
   │      vessel / components / systems / state
   ├─ World Model                    (BELUM ADA — abstraksi baru)
   └─ Developer World ↔ 3D World     (3D sudah ada; loop-nya belum)
```

***

## 📚 Indeks Blueprint

Blueprint penuh dipecah ke `docs/blueprint/` (multi-file, biar navigable
seiring visi yang kian besar). Urutan baca yang disarankan:

| # | Dokumen | Isi |
| - | - | - |
| 00 | **BLUEPRINT.md** (file ini) | Kompas strategis, keputusan arsitektur, roadmap milestone, tabel aset, risiko |
| 01 | [docs/blueprint/01-spatial-ux.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/01-spatial-ux.md) | Spatial Universe & Navigation UX (zoom ladder, camera, semantic nav, combat camera, wreckage viz, Universal Cockpit HUD, dua skala koordinat, fisika tata surya, intel-kordinat, UI command-interface) |
| 02 | [docs/blueprint/02-station-infrastructure.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/02-station-infrastructure.md) | Station & Infrastructure System (facilities, safe zone, permissions, evolution, economy) |
| 03 | [docs/blueprint/03-combat.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/03-combat.md) | Combat & World Validator / Layer I (anti-cheat, damage ceiling, fingerprint) |
| 04 | [docs/blueprint/04-wreckage-history.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/04-wreckage-history.md) | Wreckage & Hall of Fame (museum sejarah, provenance sebagai aset) |
| 05 | [docs/blueprint/05-vessel-design-dashboard.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/05-vessel-design-dashboard.md) | Vessel Design, Visual Governance & 3D Design Dashboard (creative freedom, visual policy, validation, authoring, ARCLUX Universal Baseline) |
| 06 | [docs/blueprint/06-community-social-ownership.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/06-community-social-ownership.md) | Community, Social Connection & Battlefield Ownership (access keys/trust, intelligence, component history, fleet recovery, roles, governance, asset classification, revocation, dynamic safe-zone, community splits, vessel identity, 3D, identitas sosial/aliansi/kordinat-intel, mobilisasi 2-teleport) — extension V2 + V3 |
| 07 | [docs/blueprint/07-special-capabilities.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/07-special-capabilities.md) | Special Capabilities & Player-Defined Technology (V4 — 2 capital vessels, limited activation 3x, depletion, tech lineage, component-based capability) |
| 08 | [docs/blueprint/08-persistent-world.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/08-persistent-world.md) | Persistent World / Tanpa Reset Naratif (V6 — server restart ≠ world reset, no player-initiated pause, respawn policy = keputusan ruleset terpisah) |
| 11 | [docs/blueprint/11-vessel-fitting-ux.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/11-vessel-fitting-ux.md) | Vessel Fitting UX — ekstraksi pola Pyfa (pyfa-org/Pyfa) ke model ARCLUX: slot model, stat projection real-time, capSim, damage pattern, fit code; mapping 1:1 + rencana eksekusi 4 fase (engine TS → dashboard web → gameserver → UE5). Pola boleh, kode/data Pyfa (GPL-3.0 + CCP) dilarang |
| – | [docs/blueprint/progres/](docs/blueprint/progres/) | Progres desain MMO: keputusan ([decisions-mmo.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/progres/decisions-mmo.md)) + arsitektur ([arsitektur.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/progres/arsitektur.md)) + peta implementasi ([MMO-IMPLEMENTATION.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/progres/MMO-IMPLEMENTATION.md)) |
| – | [docs/blueprint/BLUEPRINT\_LICENSE.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/BLUEPRINT_LICENSE.md) | Lisensi source-available (bukan Apache; read-only) |

***

## 1. Keputusan Arsitektur

Rekomendasi yang perlu dikunci sebelum eksekusi:

| # | Keputusan | Rekomendasi |
| - | - | - |
| K1 | Siapa hitung atribut kapal | **Hybrid**: base-stat otomatis dari analisis + user extends (validated, anti-abuse) |
| K2 | Skala pondasi | **Single-repo → 1 kapal hidup** dulu; multi-repo/war = milestone lanjutan |
| K3 | License 3-tier | Masuk pondasi pertama (bikin transfer & kompetisi adil sejak awal) |
| K4 | Rendering | Pakai `three` + `react-force-graph-3d` yang ada, extend jadi "kapal" |
| K5 | Struktur blueprint | **Multi-file** di `docs/blueprint/` (indeks ini + spec-spesifik); K2 desain |

***

## 2. Arsitektur Teknis

Ringkasan lapisan. Detail desain UX (spatial/stasiun) ada di spec terpisah.

### Layer A — `.arclux/` manifest (objek K1, K3)

Titik baru pertama: file konfigurasi ARCLUX di dalam repo user
(belum ada; gap teridentifikasi dari riset).

```
my-project/
└── .arclux/
    ├── arclux.json          # manifest: nama kapal, lisensi, override stats
    ├── vessel/
    │   └── *.arclux         # definisi kapal (DSL — engine DSL sudah ada & live)
    ├── components/          # component capability (lihat Layer C)
    ├── systems/             # subsystem def (engine/reactor/nav/defense/weapon/ai)
    └── state/               # di-generate ARCLUX, versioned (history → provenance)
```

* Definisi kapal memakai **DSL ARCLUX** (`packages/dsl`) yang sudah live di
  npm — user memakai bahasa yang ada, bukan bahasa baru.
* `.arclux/state/` = world-state yang di-generate ARCLUX, tetap versioned di
  repo user → terbawa history → nyambung ke provenance.

### Layer B — World Model (abstraksi baru; objek K1, K3)

Package baru (mis. `packages/universe/`):

```
WorldModel            # agregat status semua vessel + state universe
VesselModel           # satu kapal: base-stat (engine) + override (user) + live-state
SystemState           # per-subsystem: health/damage/degraded
ComponentBinding      # component terpasang → capability (SDK/MCP)
LicenseValidator      # K3: open/shared/private → authorized/unauthorized
ProvenanceTracker     # reuse packages/provenance → asal-usul component
DamageResolver        # simulasikan damage → lokasi modul/file yang kena
ImpactDebugger        # damage → impact tracing → baris/fungsi yang rusak
```

**Mapping stat kapal dari analisis:**

| Atribut kapal | Sumber dari ARCLUX |
| - | - |
| Armor/Integrity | `computeHealthScore` |
| Weapons | Component terpasang + security findings |
| Defense | Layer violations / attack surface |
| Engine/Navigation | Graph structure (module/node/edge counts) |
| Repair-ability | Impact tracing → file yang kena |

Ini mewujudkan "makin project berharga → makin kuat", tapi terukur &
anti-abuse (K1-C).

### Layer C — Component System (objek K3)

* Component = **capability nyata** dari SDK/MCP, bukan sekadar skin.
* Setiap component: `id`, `capability` (referensi fungsi SDK), `license`,
  `provenance`, `owner`.
* Contoh binding:
  * `security-scanner` → `analyzeRepositorySecurity`
  * `impact-solver` → `calculateAffectedFiles`
  * `route-mapper` → `mapAttackSurface`
  * `call-graph` → `buildCallGraph`
* **License 3-tier** (`LicenseValidator`):
  * 🟢 Open — boleh reuse sesuai terms
  * 🟡 Shared — butuh attribution/permission
  * 🔴 Private — hanya owner & yang diizinkan; unauthorized → **capability
    disabled** (bukan code rusak)

### Layer D — Ingestion & Auto-Update (objek K2)

* **Connect**: `arclux connect <repo-url>` (npm/CLI/MCP/SDK yang sudah live)
  → membuat boilerplate `.arclux/`.
* **Auto-update**: daemon (`packages/daemon/`) + watcher
  (`packages/watcher/`) → event `analysis:updated` → update `VesselModel`
  → push ke web.
  * **Gap**: web belum consume SSE daemon (`/events`). Perlu bridge route
    Next.js (`/api/universe/events`) + `EventSource` client.
  * **Gap jangka panjang**: `watchRepository` masih full-rebuild; true
    per-file incremental (`packages/incremental`) belum di-wire ke
    `buildIndex`.

### Layer E — 3D World (objek K2, K4)

* Render hub/dashboard memakai `three` yang sudah ada.
* 3D kapal: extend pola `GraphCanvas3D` + `GraphAuditOverlay` (terbukti bisa
  drive scene dari luar via `fgRef`).
* Mapping: sistem kapal → mesh 3D, health → warna/scale/partikel damage.
* Kualitas adaptif (resolution/FPS/effects/render distance) — render di
  client, sim tetap di world-state (FPS tidak menentukan kebenaran sim).
* **Spatial & navigation UX penuh** (zoom ladder, camera modes, semantic
  navigation, adaptive HUD, LOD, combat camera) — lihat
  [docs/blueprint/01-spatial-ux.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/01-spatial-ux.md).

### Layer F — Developer World → Debug

* **Health Dashboard**: game-HUD + observability; tiap subsystem → health%,
  click-through ke modul/file/baris (via `ImpactDebugger` +
  `packages/editor/CodeNavigator` + `packages/impact/*`).
* **"Repair = commit"**:
  1. Damage → `DamageResolver` identifikasi modul terkait
  2. Dev debug & update code
  3. Commit → ARCLUX re-analyze
  4. `VesselModel` update → health pulih

### Layer G — Server/Infra (objek K3)

* Sebagian besar workload di client/user runtime (render + sebagian sim).
* Server/global cuma: identity, sync, persistence, world-events, validation,
  permissions.
* Persistence pakai `packages/db` + `packages/storage/RecoveryManager`.
* Community/fleet/station/territory/hall-of-fame = milestone lanjutan
  (lihat [docs/blueprint/02-station-infrastructure.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/02-station-infrastructure.md)).

### Layer H — Business & Ecosystem

* **Monetisasi**: core sudah `arclux` live di npm. Tier: free core + premium
  SDK/MCP/enterprise + storage/history + advanced universe component.
* **Collaborator ecosystem**: extension di atas ARCLUX (SDK, sandbox,
  validation, publish) — tanpa write access ke core. Fondasi ada di
  `packages/shell/plugins.ts` + `detectors.ts` (user-space).

### Layer I — Combat & World Validator (Anti-Cheat)

Ringkasan — detail penuh di
[docs/blueprint/03-combat.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/03-combat.md).

> **Visual boleh cinematic. Hasil harus deterministic + tervalidasi.**
> *"Users create the machines. ARCLUX defines the physics. The server
> verifies reality."*

**I.1–I.8** — visual serangan (archetype, client-render); damage per-subsystem;
catastrophic → wreckage; World Validator (server = referee, validasi tiap
request); vessel state fingerprint; component authorization; damage ceiling;
replay/event log.

***

## 3. Roadmap Milestone

### Milestone 1 — "Kapal Hidup" (pondasi)

1 repo → 1 kapal yang hidup & bisa dijelajah. Validasi loop inti (#2-4, #7-10).

* `.arclux/` schema + generator (`arclux connect`)
* World Model core (`VesselModel`, `SystemState`, stat mapping, `ComponentBinding`)
* Health Dashboard di `apps/web` (hub 2D)
* 3D vessel (extend `GraphCanvas3D` jadi mesh kapal sederhana)
* License 3-tier validation (`LicenseValidator` + provenance) — K3
* Bridge SSE daemon→web (auto-update)
* `arclux connect` + docs

**Out of scope M1:** perang menyeluruh, multi-repo universe, transfer antar
kapal, fleet/community, hall-of-fame, global server, station.

### Milestone 2 — "War & Damage"

* Damage simulation + `DamageResolver` + `ImpactDebugger`
* Component rusak → capability turun; repair = commit
* Catastrophic damage threshold → rebuild via commit
* Multi-repo connect + war 2 kapal (tak merusak repo asli)
* Combat renderer (visual cinematic) + World Validator (anti-cheat) — Layer I
* Vessel state fingerprint, component authorization, damage ceiling, replay log
* Awal spatial navigation antar vessel (zoom ladder dasar, kamera follow) —
  [01-spatial-ux.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/01-spatial-ux.md)

### Milestone 3 — "Universe Persisten"

* Persistent world-state (server sync, identity, events)
* Transfer component antar kapal + provenance transfer
* Wreckage Archive + Hall of Fame (museum sejarah) — lihat
  [04-wreckage-history.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/04-wreckage-history.md)
* **Station awal** (outpost/hub dasar: dock, engineering, analysis lab,
  safe zone) — lihat
  [02-station-infrastructure.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/02-station-infrastructure.md)
* Semantic navigation penuh (show-in-universe ↔ show-in-code)

### Milestone 4 — "Ecosystem & Economy"

* Extension Registry + publish + discovery
* Community/fleet/station/territory
* Station evolution (outpost → hub → fleet base / landmark), component market,
  navigation & security center, observatory
* Economic loop penuh
* Spatial zones (open/combat/safe/planetary/travel/special) — ruleset per zone

***

## 3b. Wreckage & Hall of Fame — Museum Sejarah

Ringkasan — detail penuh di
[docs/blueprint/04-wreckage-history.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/04-wreckage-history.md).

Kapal yang hancur tidak "respawn lalu hilang". Ia meninggalkan **puing
sejarah** yang permanen dan menjadi aset dunia. Puing membawa **provenance**
(jejak hidup sebuah component: dibuat → dipasang → dipindah → hancur →
recovered → Hall of Fame). Hall of Fame = museum sejarah, bukan leaderboard.

**Filosofi yang konsisten:** ARCLUX tidak perlu membuat semua cerita.
Developer & komunitas menciptakan kejadian → ARCLUX menyimpan &
memvisualisasikan sejarahnya. Itulah yang membuat ARCLUX terasa seperti
**dunia**, bukan sekadar game yang punya map.

***

## 4. Yang Sudah Ada vs Harus Dibangun

| Kebutuhan | Status | Keterangan |
| - | - | - |
| npm CLI/MCP/SDK/DSL | ✅ ADA | `arclux` live |
| 3D engine (`three`) | ✅ ADA | `apps/web`, `GraphCanvas3D` |
| Scene drive dari luar (`fgRef`) | ✅ ADA | `GraphAuditOverlay` |
| Daemon + SSE live-push | 🟡 | daemon ada; web belum consume SSE |
| Persistensi + history trend | ✅ ADA | `AnalysisRecord` |
| Provenance | 🟡 | `ProvenanceRecord` ada; `Revision/Snapshot` stub |
| User-space plugin/detector | ✅ ADA | `packages/shell/plugins.ts` |
| Impact tracing → debug map | ✅ ADA | `packages/impact/*` |
| Crash-safe storage | ✅ ADA | `RecoveryManager` |
| Config `.arcluxrc` di repo user | ❌ BELUM | titik baru |
| World Model / VesselModel | ❌ BELUM | abstraksi baru |
| License validation | ❌ BELUM | bikin baru |
| Damage/simulation engine | ❌ BELUM | bikin baru |
| Combat renderer (visual cinematic) | ❌ BELUM | archetype visual, client-side render |
| World Validator (anti-cheat) | ❌ BELUM | referee; state fingerprint, authorization, damage ceiling, replay |
| Wreckage Archive / Hall of Fame | ❌ BELUM | museum sejarah; pakai provenance + db |
| Spatial Universe & Navigation UX | ❌ BELUM | zoom ladder, semantic nav, combat camera, adaptive HUD, LOD |
| Station & Infrastructure | ❌ BELUM | facilities, safe zone, permissions, evolution, economy |
| Global server | ❌ BELUM | baru di M3+ |
| True per-file incremental | 🟡 | built, belum di-wire ke `buildIndex` |

***

## 5. Risiko & Pertanyaan Terbuka

1. **Anti-abuse & fairness (K1-C):** gimana user extends base-stat tanpa jadi
   pincang? Butuh rule: override cap / atribut yang tak bisa diubah.
2. **Validasi sentral vs lokal:** untuk kompetisi adil, mungkin butuh server
   validation di M2+ war.
3. **"Perang" perlu attack surface yang adil** — tuning supaya tak mudah 1-hit-KO.
4. **Skala visi besar:** M1 harus dikunci supaya arsitektur tak melenceng saat
   ke M2-M4.
5. **Anti-cheat combat:** arsitektur "server sebagai referee, client hanya
   render" mengharuskan world-state yang terpusat & ter-version (fingerprint,
   replay log) — ini menambah kebutuhan server validation yang lebih kuat
   dibandingkan M1 single-repo.
6. **Latency & determinism:** karena hasil ditentukan server, perlu desain
   input-queue + event replay agar dua client melihat kejadian konsisten.
7. **Abstraction zoom ladder:** seberapa dalam ladder (Universe → … → Code)
   bersifat tetap vs adaptif terhadap kedalaman repo sebenarnya
   (lihat [01-spatial-ux.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/01-spatial-ux.md) — Abstraction
   Zoom System).
8. **Station scale:** sistem station harus mendukung ribuan station tanpa
   jadi monolit — ARCLUX membangun rules, bukan membuat station satu-per-satu
   (lihat [02-station-infrastructure.md](https://github.com/GSF-001/ARCLUX/blob/main/docs/blueprint/02-station-infrastructure.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.