Archestack in VS Code

Mit der Archestack-Erweiterung für Visual Studio Code ist deine App ein git-Repository und läuft auf deinem eigenen Rechner. Öffne den Ordner des Repositorys, und die Erweiterung startet dafür ein lokales Archestack: PostgreSQL, die API und den Builder, aus der Laufzeitumgebung, die die Erweiterung mitbringt. Es gibt keinen Workspace, mit dem du dich verbinden musst, und sonst nichts zu installieren. Script Modules, Business Events, Pages, Templates und Tabellen sind Dateien im Ordner, und jede Datei, die du speicherst, kommt einen Moment später im lokalen Archestack an.

Dieses lokale Archestack heißt Projekt. Es gehört zum Repository: Ein Teamkollege, der es klont, bekommt dasselbe Projekt, aus denselben Dateien erstellt. Im Team arbeiten beschreibt, wie sich die Entwickler eines größeren Unternehmens ein Repository teilen, und Die VS Code-Erweiterung im Detail zeigt jeden Bildschirm.

Installieren

Die Erweiterung ist noch nicht im Visual Studio Marketplace. Sie kommt als VSIX-Datei: Öffne in VS Code die Command Palette, führe Extensions: Install from VSIX... aus und wähle die Datei. Sie braucht VS Code 1.90 oder neuer.

Nimm den Windows-Build (x64). Er bringt die Archestack-Laufzeitumgebung mit, also die API, den Builder und PostgreSQL, sodass ein Projekt läuft, ohne dass sonst etwas installiert ist. PDFs werden im Edge oder Chrome gerendert, der schon auf dem Rechner ist. Der universelle Build hat keine Laufzeitumgebung und lässt Projekte stattdessen in Docker Desktop laufen.

Die Erweiterung braucht weder die C#-Erweiterung von Microsoft noch das C# Dev Kit. Ihre C#-Funktionen kommen vom Projekt selbst, und ihre Skripte öffnen sich in einer eigenen Sprache, daher kann beides installiert bleiben, ohne dass sich die beiden in die Quere kommen.

Ein Projekt starten

• Eine neue App. Öffne einen leeren Ordner, öffne die Ansicht Archestack in der Aktivitätsleiste und wähle Start project. Die Erweiterung legt archestack.json an, erstellt eine frische Datenbank, startet die API und den Builder und meldet sich von selbst als Admin des Projekts an. New Package legt danach den ersten Package-Ordner an.
• Ein bestehendes Repository. Klone es und öffne seinen Ordner. Das Fenster startet das Projekt von selbst: Der erste Start legt die Datenbank an und lädt das Repository hinein, zuerst die Tabellen jedes Packages, dann die Artefakte, Abhängigkeiten vor den Packages, die sie brauchen. Ein frischer Clone ist in etwa fünfzehn Sekunden eine funktionierende App, und öffnest du das Fenster erneut, macht es mit dem Projekt weiter.

Das Projekt ist in archestack.json beschrieben, und diese Datei wird committet:

"project": {
  "name": "archestack-sales",
  "engine": "native",
  "webPort": 5310,
  "dbPort": 5312,
  "adminEmail": "admin@archestack.local"
}

Builder und API teilen sich webPort, und PostgreSQL lauscht auf dbPort, beide nur auf 127.0.0.1. Die Datenbank des Projekts, seine erzeugten Passwörter und seine Logs liegen in .archestack/project/, das git ignoriert. Die NuGet-Pakete, die seine Skripte herunterladen, werden ebenfalls dort aufbewahrt, in .archestack/project/nuget, oder in einem Docker-Volume namens nuget, wenn das Projekt in Docker läuft, sodass ein Neustart sie nicht erneut herunterlädt.

Die Statusleiste zeigt das Projekt als local. Ihre Liste öffnet den Builder des Projekts im Browser, stoppt das Projekt und zeigt die Logs der API. Reset Project Database wirft die Daten des Projekts weg und lädt das Repository neu hinein.

Das Projekt gehört zu dem Fenster, in dem es läuft. Das Fenster zu schließen oder neu zu laden stoppt die API und PostgreSQL, es läuft also nichts weiter, und das nächste Fenster startet sie in Sekunden wieder. Antwortet die API nicht mehr, während du arbeitest, startet das Fenster sie innerhalb von zehn Sekunden neu.

Das Repository

Ein Repository enthält einen Ordner pro Package und eine oder mehrere Dateien pro Artefakt:

archestack.json                 the environments this repository knows, and its packages
packages/sales/
  package.json                  name, version, dependencies
  nuget.json                    the NuGet packages its scripts use, each at an exact version
  tables/orders.json            one per table: columns, keys, indexes, foreign keys
  layout.json                   where the tables sit on the diagram
  entities/Order.json
  scripts/Calc.csx + Calc.json  a script module: its code, and its parameters
  code/Sales/OrderSummary.cs    shared code, named by its path: C# every script can use,
  code/components/StatusChip.tsx  and modules pages import from @/
  triggers/Order/OnCreate.json + OnCreate.1.csx
  pages/Orders/page.json + overview.tsx + OrderRow.tsx   a page's own files beside its views
  templates/Card/template.json + template.tsx
  pdf/Invoice/template.json + template.html + data.csx
  schedules/nightly.json
  tests/smoke/suite.json + cases/doubles.json + doubles.csx
  api/customers.json            a Data API endpoint, named by its route, every version inside
workspace/
  branding.json, logo.png, layouts.json

Verweise zwischen Artefakten sind Namen, nie Datenbank-IDs. Nichts, was pro Umgebung entschieden wird, steht in den Dateien: Wer eine Page sehen darf, ob etwas öffentlich ist, Data-API-Freigaben und die Laufhistorie bleiben bei jeder Umgebung. Derselbe Inhalt ergibt immer dieselben Bytes, git zeigt also nur echte Änderungen.

Das Projekt bekommt den Ordner beim Speichern zugespielt. Eine gespeicherte Änderung unter packages/ kommt einen Moment später dort an, und was du im Ordner löschst, wird dort gelöscht, auch ein ganzer Package-Ordner. Es gibt nichts zu pushen. Tabellen sind die Ausnahme: Sie ändern sich über Migrationen.

New Package legt einen Package-Ordner an, und New Artifact in Package (Rechtsklick auf etwas unter packages/ im Explorer, oder + an einem Package in der Workspace-Ansicht) schreibt die Dateien eines neuen Artefakts und fragt dabei nur nach dem, ohne das es nicht existieren kann, etwa nach der Entity, zu der ein Business Event gehört. Eine neue Page ist eine Code-Page. Eine neue Shared-Code-Datei fragt nach ihrem Pfad, und ihre Endung sagt, was sie ist. Add File an einem Artefakt in der Workspace-Ansicht legt eine Datei daneben an: Eine Page bekommt eine eigene Datei neben ihren Views, die sie als ./Row importieren, und ein Script Module, Business Event oder anderes Script, das aus einer einzigen Datei besteht, bekommt eine Shared-Code-Datei im selben Package, in einem Ordner mit seinem Namen, die jedes Script verwenden kann.

Der Builder des Projekts funktioniert auch, im Browser. Eine Änderung, die dort gemacht wird, ist erst im Ordner, wenn du sie mit Pull Package to Folder hereinholst, und ein Package, das an beiden Stellen geändert wurde, bleibt unangetastet, was einmal gemeldet wird, sodass nichts überschrieben wird. Committe, was du pullst, wie jede andere Änderung.

Artefakte bearbeiten

Der Code eines Artefakts ist eine Datei, und seine Einstellungen sind das JSON daneben, das sich in einem Formular öffnet. Jede Änderung im Formular wird in die Datei geschrieben; Edit as JSON öffnet den Text.

Eine Business Entity öffnet sich im Entity-Editor. Ihre Tabellen und Spalten werden aus der Datenbank des Projekts ausgewählt, ein Name, der nicht existiert, wird also markiert, bevor du speicherst. Die eigenen Einstellungen des Workspaces sind ebenfalls Dateien, in workspace/: das Branding mit seinen Logos und die Layouts der veröffentlichten App, die sich jeweils in einem Formular öffnen.

C#-Skripte

Script Modules, Business-Event-Skripte, PDF Data Scripts, Scheduled Events und Testskripte bekommen die C#-Funktionen eines .NET-Editors. Sie werden vom eigenen Compiler des Projekts beantwortet, der Editor sieht also genau das, was das Skript sieht, wenn es läuft:

• Vervollständigungen, mit der Signatur und der Dokumentation jedes Members.
• Hover und Parameterinfo, während du einen Aufruf tippst.
• Fehler und Warnungen beim Tippen.
• Go to Definition (F12). Auf der Methode eines Script Modules öffnet es das Skript dieses Moduls, auf einem Parameter die Einstellungen, die ihn deklarieren, und auf allem anderen dessen Deklarationen, schreibgeschützt.
• Format Document, im .NET-Stil.

Der Editor kennt die echten Skript-Globals (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc und Log), die Parameter eines Moduls als typisierte Variablen und in einem Business Event die Spalten der Entity auf Entity. Business Entities sind typisierte Sets auf Db und Script Modules typisierte Methoden auf Modules, eine umbenannte Spalte oder ein falsches Argument ist also ein Fehler in seiner Zeile, bevor irgendetwas läuft:

// A script module is a typed method: a wrong name or argument is an error as you type
var total = await Modules.Calc(qty: 2);

// Every business entity is a typed set
var open = await Db.Order
    .Where(o => o.Status == "Open")
    .ToListAsync();

Business Entities als typisierte Sets auf der Reference-Seite erklärt, wie die Namen gebildet werden.

Typen, die mehr als ein Skript braucht, etwa Records und Helper, gehören als Shared Code in eine C#-Datei im Ordner code/ eines Packages. Sie ist gewöhnliches C#, bekommt dieselben Funktionen, und F12 auf einem ihrer Typen in einem Skript öffnet sie. Shared Code auf der Reference-Seite erklärt, was eine Shared-Code-Datei verwenden kann.

Bibliotheken von NuGet werden in der nuget.json des Packages deklariert, jede in einer genauen Version, und ihre Typen werden wie der Rest vervollständigt, sobald der Workspace sie heruntergeladen hat. Siehe NuGet Packages auf der Reference-Seite.

Ein Script Module testen

Test über dem Code eines Script Modules führt das Modul so aus wie der Test-Tab im Builder, mit dem Skript, wie es im Editor steht, gespeichert oder nicht. Du findest es auch in der Titelleiste des Editors, am Modul in der Workspace-Ansicht und in seinem Formular. Ein Panel neben dem Skript fragt nach den Parametern, prüft jeden Wert gegen seinen Typ und merkt sie sich für das nächste Mal. Ein Modul, das keinen Wert braucht, den es nicht schon hat, läuft sofort, und Ctrl+Enter im Panel führt es erneut aus. Das Panel zeigt, ob der Test bestanden ist, was das Modul zurückgegeben und was es in Log geschrieben hat, und bei einem Fehler die Meldung mit einem Button zu ihrer Zeile.

Ein Test ist ein Probelauf: Schreibvorgänge über Db und Files werden aufgelistet statt ausgeführt, Mails und Benachrichtigungen aufgelistet statt gesendet, auch die der Module, die es aufruft. Alles andere, was das Skript selbst tut, ist echt: HTTP-Aufrufe, System.IO und alles, was ein NuGet-Paket tut, etwa eine Verbindung zu einer anderen Datenbank. Setze den Haken bei Show the SQL it ran, um seine Statements im Panel SQL Trace zu sehen. Testen dürfen nur Admins und Owner. Ein Test sagt, was ein Lauf tut; eine Prüfung, die jedes Mal läuft, ist ein Testfall, siehe Tests.

Page- und Template-Code

Der Code einer Page und die .tsx eines Frontend Templates werden gegen das geprüft, was dieser Code zur Laufzeit wirklich hat: backend, pageContext, currentUser, die Hooks, React, jede MUI-Komponente mit ihren Props, die Icons und einen Zeilentyp für jede Business Entity, etwa CustomerRow. Vervollständigungen, Hover, Fehler, Go to Definition, Umbenennen und Format Document funktionieren alle, und ein return auf oberster Ebene ist in Ordnung. Das läuft auf dem TypeScript, das mit VS Code kommt, es muss also nichts installiert werden.

Code lässt sich auf mehrere Dateien verteilen. Die eigenen Dateien einer Page liegen in ihrem Ordner neben den Ansichten und werden als ./OrderRow importiert; Code, den mehr als eine Page verwendet, gehört in den Ordner code/ eines Packages und wird über @/ importiert, von jedem Package des Repositorys aus. Imports werden geprüft und typisiert, Go to Definition folgt ihnen, und eine Umbenennung ändert jede Datei, die den Namen verwendet.

What page code can use, der Link über dem Code jeder Page und jedes Templates, öffnet daneben die vollständige Liste: jedes Global mit dem, was es tut, und einem Beispiel, sowie die Zeilentypen des Projekts. Der Builder zeigt dieselbe Liste.

Vorschauen

Open Preview to the Side, der Button oben rechts in einem PDF Template, einem Frontend Template, dem Code einer Page oder einem App Layout, zeigt es so, wie es im Editor steht, gespeichert oder nicht, und folgt jeder Änderung:

• Ein PDF Template wird vom Projekt gerendert. Sein Data Script läuft als Probelauf, eine Vorschau schreibt also nie eine Zeile und verschickt nie eine Mail. Parameterwerte lassen sich oben ändern.
• Ein Frontend Template oder eine Page wird von der eigenen App des Projekts gerendert, mit den Parametern des Templates oder der Datensatz-ID der Page oben, und mit den eigenen Dateien der Page und dem Shared Code des Repositorys so, wie sie in ihren Editoren stehen. Eine Page wird im App Layout gezeichnet, das die veröffentlichte App um sie legt; die Werkzeugleiste wechselt zu einem anderen Layout oder zu keinem.
• Ein App Layout wird von der eigenen Shell der veröffentlichten App gezeichnet, für eine Page, die du auswählst.
• Ein Template, eine Page oder ein Layout lässt sich auf einem Handy, Tablet oder Desktop in echter Größe zeigen, im Querformat oder in einer eigenen Größe, und passend oder auf einen Prozentwert zoomen. Die nächste Vorschau öffnet auf dem Gerät, das du zuletzt gewählt hast.

Tabellen

Die Tabellen eines Packages sind Dateien, packages/<package>/tables/<table>.json, eine pro Tabelle. Sie öffnen sich im Tabelleneditor: Spalten mit ihren Typen, Schlüsseln, Defaults und Fremdschlüsseln sowie die Indizes der Tabelle. Die Ansicht Database listet die Tabellen des Projekts; Open Database Diagram zeichnet sie mit ihren Fremdschlüsseln, und eine Tabelle dort zu ziehen schreibt die layout.json des Packages. New Table fragt, zu welchem Package die Tabelle gehört.

Eine Tabellendatei zu speichern ändert die Datenbank des Projekts nicht. Der Rest des Ordners wird eingespielt, und die Workspace-Ansicht und eine Meldung sagen, welche Tabellenänderungen auf eine Migration warten. Eine frische Projektdatenbank, beim ersten Start oder nach einem Reset, bekommt die Tabellen des Ordners von selbst.

Migrationen und Rollback

Add Migration plant die Tabellenänderungen gegen die Datenbank des Projekts und zeigt jede Operation, ihr Risiko und das genaue SQL. Operationen, bei denen Daten verloren gehen, etwa das Löschen einer Tabelle oder Spalte oder das Verengen eines Typs, brauchen ein Häkchen bei Allow data loss. Die Überprüfung listet außerdem die typisierten Skripte, die nach der Änderung nicht mehr kompilieren würden. Die Migration wird als ausstehendes Deployment mit einem Namen gespeichert, der aus dem vorgeschlagen wird, was sich ändert, etwa AddTechnicianSkill; Deploy führt sie aus, und Add and Deploy macht beides auf einmal.

Die Ansicht Deployments ist die Historie, das neueste zuerst. Show SQL zeigt, was ein Deployment ausführt. Roll Back to Here plant, die Tabellen auf den Stand zurückzubringen, den ein früheres Deployment hergestellt hat, und fügt das als eigenes ausstehendes Deployment hinzu, das du wie jede Migration prüfst und deployst. Ein Rollback stellt die Struktur wieder her, nie die Daten: Die Zeilen in einer Tabelle oder Spalte, die er entfernt, sind weg.

Drop Table entfernt die Datei der Tabelle und markiert die Tabelle; sie verschwindet, wenn eine Migration mit erlaubtem Datenverlust deployt wird.

SQL-Konsole

New SQL Query öffnet einen SQL-Editor auf der Datenbank des Projekts, mit Vervollständigung für Tabellen und Spalten. Run Query (Ctrl+Enter) führt die Auswahl oder die ganze Datei aus, Statement für Statement, jedes für sich committet, und stoppt beim ersten Fehler. Ergebnisse öffnen sich neben dem Editor, bis zu 1.000 Zeilen pro Ergebnis, und lassen sich als CSV kopieren. Vor einem DELETE fragt nichts nach.

Abfragepläne und SQL-Traces

Explain Query zeigt den Plan, den PostgreSQL für die Auswahl wählt, oder für das Statement, in dem der Cursor steht: jeden Schritt, was er liest und wie viele Zeilen er erwartet. Explain Analyze Query (Ctrl+Alt+Enter) führt das Statement aus, um echte Zeiten und Zeilenzahlen zu bekommen, in einer Transaktion, die zurückgerollt wird, sodass selbst ein DELETE seine Zeilen behält. Der Plan markiert den Schritt, der die meiste Zeit braucht, und was einen zweiten Blick wert ist: einen Scan, der Tausende Zeilen liest, um wenige zu behalten, eine Zeilenschätzung weit weg von dem, was zurückkam, eine Sortierung, die auf die Festplatte ausweichen musste.

Trace SQL zeigt das SQL, das Archestack selbst sendet. Klicke in der Workspace-Ansicht mit der rechten Maustaste auf ein Script Module oder eine Business Entity, oder nimm den Button an ihrer Datei oder ihrem Formular. Ein Script Module läuft mit den Parameterwerten, die du angibst, standardmäßig als Probelauf, dessen Schreibvorgänge aufgezeichnet statt ausgeführt werden. Eine Business Entity wird so gelesen, wie das Grid einer Page sie liest. Das Panel SQL Trace listet dann jedes Statement mit seinen Werten, wie lange es gedauert hat und dem Code, der es gesendet hat, und kann gleiche Statements zusammenfassen, um eine Abfrage zu zeigen, die einmal pro Zeile läuft. Klicke auf ein Statement, um seinen Plan anzuzeigen, es mit eingesetzten Werten als SQL zu öffnen oder es zu kopieren. In der Ansicht Testing macht Run with SQL Trace dasselbe für Testfälle. Tracen dürfen nur Admins und Owner.

Tests

Run Tests in der Workspace-Ansicht führt die Tests aller Packages aus, die eines Packages, eine Suite oder einen einzelnen Testfall. Der Ordner wird zuerst in das Projekt eingespielt, ein Testfall prüft also die Skripte und Pages so, wie sie im Ordner liegen. Jeder Testfall läuft in einer Test-Sandbox, einer eigenen Datenbank, nie gegen die Daten des Projekts, und Mails und Benachrichtigungen werden aufgezeichnet statt verschickt. Vier Testfälle laufen gleichzeitig. Jeder Testfall zeigt im Baum sein letztes Ergebnis und wie lange er gedauert hat; ein Klick darauf zeigt, was fehlgeschlagen ist, Erwartung gegen Ist-Wert, und was er ausgegeben hat. Die Ansicht Testing listet dieselben Testfälle.

Eine Prüfung, die sich nicht mit einem Subjekt und einem Operator ausdrücken lässt, ist eine Code-Prüfung: eine eigene C#-Datei, die nach dem Testfall läuft, mit Result, Output, Error und Failed zur Hand, und die fehlschlägt, wenn sie eine Exception wirft, ein Assert nicht besteht oder false zurückgibt.

Event Log

Die Ansicht Event Log zeigt, was im Projekt gelaufen ist, gruppiert nach Art: Business Events, Script Modules, Scheduled Events, Testläufe, Mail und Backups, jeweils mit den Läufen und Fehlschlägen des letzten Tages. Ein neuer Fehlschlag wird im Badge der Ansicht gezählt und gemeldet, sobald er passiert. Klick auf einen Eintrag, um alles zu lesen, was er aufgezeichnet hat. Open Artifact öffnet die Datei des Skripts, in dem er fehlgeschlagen ist, auf der fehlerhaften Zeile.

Data API

Ein Data-API-Endpunkt stellt eine Business Entity anderen Systemen bereit, unter einer Adresse wie /api/data/v1/customers. Er gehört wie jedes andere Artefakt zu einem Package: eine Datei, api/customers.json, benannt nach seiner Route und mit allen seinen Versionen. Die Datei öffnet sich in einem Formular: die Entity, die er bereitstellt, sein Name und seine Route und je Version der Status, der Sunset-Tag, die Seitengröße, die Operationen und die Felder. Jedes Feld ist ein öffentlicher Name über einer Spalte der Entity, zurückgegeben, schreibbar oder Pflicht; das Formular bietet die Spalten an und markiert ein Feld, dessen Spalte die Entity nicht hat.

Ein Endpunkt kann stattdessen ein Script Module aufrufen, für Arbeit, die mehr ist als Zeilen zu lesen oder zu schreiben. Jede Version nennt das Modul und die eine Methode, auf die sie antwortet, POST mit den Parametern in einem JSON-Body oder GET mit ihnen im Query-String, und listet die Parameter auf, die Aufrufer senden: ein öffentlicher Name über einem Parameter des Moduls, Pflicht oder nicht, mit einer Beschreibung. Das Formular bietet die Parameter des Moduls an und markiert einen, den das Modul braucht, die Version aber nicht übergibt. Ein Aufrufer bekommt, was das Modul zurückgibt, als JSON. Ein als admin only markiertes Modul bleibt es: Nur Admins und Owner dürfen es aufrufen, sein Endpunkt bekommt also keine Freigaben.

Eine veröffentlichte Version kann nur noch wachsen. Felder und Operationen hinzuzufügen ist in Ordnung; ein Feld zu entfernen oder umzubenennen, ihm den Schreibzugriff zu nehmen, es zur Pflicht zu machen oder eine Operation zu streichen, würde die Systeme brechen, die es aufrufen. Das gehört deshalb in eine neue Version, die das Formular als Kopie der angezeigten beginnt. Bei einem Endpunkt, der ein Script Module aufruft, behält die Version ihr Modul und ihre Methode und bekommt nur optionale Parameter hinzu. Ein Speichern, das eine veröffentlichte Version bricht, wird abgelehnt, mit Begründung. Eine Version zu aktivieren bietet an, die älteren als veraltet zu markieren; diese werden weiter bedient und sagen Aufrufern in ihren Headern, dass sie veraltet sind, und, sobald du einen setzt, ihren Sunset-Tag, bis du sie auf Retired setzt.

Die Ansicht Data API listet die Endpunkte des Projekts mit ihren Versionen und seine API-Clients. Try It auf einem Endpunkt oder einer Version sendet echte Requests und zeigt die Antwort so, wie sie ankam, samt Headern: als du selbst, auf Wunsch mit dem ausgeführten SQL, oder mit dem Schlüssel eines API-Clients, um genau zu sehen, was dieser Client aufrufen darf. Auf einem Endpunkt, der ein Script Module aufruft, sendet es den Aufruf mit Beispielparametern. Die Schaltflächen der Ansicht öffnen das OpenAPI-Dokument mit allem, was du aufrufen darfst, und How to connect, den Leitfaden für alle, die darauf aufbauen.

Wer einen Endpunkt aufrufen darf, entscheidet jede Umgebung selbst, und es steht nie in der Datei. Edit access in the workspace im Formular öffnet die Freigaben: welche Rollen auflisten, lesen, anlegen, ändern oder löschen oder das Modul aufrufen dürfen. Ein API-Client ist ein Dienstkonto mit Rollen und einem Schlüssel statt eines Passworts. New API Client legt einen an und zeigt seinen Schlüssel einmal; Rotate Key ersetzt ihn, und der alte Schlüssel funktioniert sofort nicht mehr.

Coding-Agents

Das Repository sagt Coding-Agents wie Claude Code und Codex, was sie darin anlegen können, so wie der MCP Server es einem verbundenen Modell sagt. New Package und jeder Pull schreiben:

• AGENTS.md: wie eine Änderung die App erreicht, die Regeln, denen jede Datei folgt, die Fehler, die zu vermeiden sind, und ein Beispiel für jede Art von Artefakt. Nur der markierte Abschnitt der Erweiterung wird neu geschrieben, die eigenen Notizen deines Teams in der Datei bleiben also erhalten.
• CLAUDE.md, das Claude Code auf AGENTS.md verweist.
• docs/archestack/: die Skript- und Test-Guides und was Page-Code verwenden kann. Der Ordner wird committet, ein Agent, der an einem frischen Clone arbeitet, hat sie also auch.
• .archestack/context/: die Business Entities des Projekts und sein erzeugtes Datenmodell, nur für diesen Rechner.

Update Agent Instructions schreibt sie neu. Die Änderungen eines Agents sind gespeicherte Dateien wie deine, sie erreichen das Projekt also auf demselben Weg; ein Mensch prüft und committet sie.

Im Team arbeiten

Für ein größeres Unternehmen ist das Repository die maßgebliche Quelle der Anwendung, so wie Infrastructure as Code Server beschreibt: Alles, woraus die App besteht, ist eine Datei in git, geprüft und versioniert wie jeder andere Code, und jede Umgebung entsteht aus diesen Dateien. Mit der Erweiterung arbeitet jeder Entwickler daran.

Entwickler 1

Repository-Dateien Lokales Projekt

Entwickler 2

Repository-Dateien Lokales Projekt

Entwickler 3

Repository-Dateien Lokales Projekt

Push und Pull

Git-Server

Das Repository: Branches, Pull Requests und main

Pipeline

Build, Test, Planen, Deployen

Test

Gehostetes Archestack

Abnahme

Gehostetes Archestack

Produktion

Gehostetes Archestack

Jeder Entwickler lässt seine eigene Kopie laufen

Jeder Entwickler klont das Repository und öffnet es, und sein Fenster lässt ein eigenes Projekt laufen, mit einer eigenen Datenbank, auf seinem eigenen Rechner. Niemand teilt sich einen Entwicklungs-Workspace, niemand speichert also über die Arbeit eines anderen, und ein Skript, das kaputtgeht, bleibt auf einem Rechner, bis es repariert ist. Bei einem neuen Teammitglied läuft die App etwa fünfzehn Sekunden nach dem Clone. Die Tabellen eines Projekts sind anfangs leer, und Testfälle schreiben die Zeilen, die sie brauchen, in ihre eigene Sandbox, sodass jeder Entwickler gegen dieselben Daten testet.

Ein Package pro Team

Eine große App besteht aus mehreren Packages, jedes ein Ordner mit eigenen Tabellen, Business Entities, Pages, Skripten und Tests. Teile sie so auf, wie das Unternehmen aufgeteilt ist, dann arbeiten Teams meist in eigenen Ordnern:

packages/
  core/        customers, products, shared scripts     team Platform
  sales/       quotes and orders, needs core           team Sales
  planning/    work orders and schedules, needs core   team Operations
  invoicing/   invoices and PDF templates, needs sales team Finance

Ein Package nennt die Packages, die es braucht, in seiner package.json, mit Namen und Versionsbereich:

{
  "formatVersion": 1,
  "name": "invoicing",
  "version": "1.4.0",
  "description": "Invoices and their PDFs, made from sales orders.",
  "dependencies": [
    { "name": "sales", "versionRange": "[2.0,3.0)" }
  ],
  "masterData": []
}

Eine bloße Version wie 2.0 bedeutet diese Version oder neuer, [2.0] genau diese, und [2.0,3.0) alles ab 2.0 bis ausschließlich 3.0. Ein Projekt lädt Abhängigkeiten vor den Packages, die sie brauchen. Eine Tabelle, die einem anderen Package gehört, wird als reine Referenz mitgeführt: Ein Package kann mit einem Fremdschlüssel auf sie zeigen, ändert sie aber nie. Die Code-Owners-Funktion deines git-Hosts kann dann für jeden Ordner ein Review durch das Team verlangen, dem er gehört.

Oder ein Repository pro Team

Teams, die auch nach ihrem eigenen Zeitplan ausliefern sollen, können stattdessen jeweils ein eigenes Repository besitzen und damit eine eigene App, ein eigenes Projekt und eigene Umgebungen. Die Daten, die einem Team gehören und die ein anderes braucht, erreichen das andere als Third-Party-Tabellen: Seine Umgebungen verbinden sich mit der Datenbank des Teams, dem sie gehören, und spiegeln die Tabellen, die sie brauchen, nach Zeitplan. Eine gespiegelte Tabelle liest sich wie jede andere Tabelle der App, in Business Entities, Pages und Skripten.

sales-app/       team Sales        owns customers, quotes and orders
planning-app/    team Operations   mirrors customers from sales-app
invoicing-app/   team Finance      mirrors customers and orders from sales-app

• Ein Besitzer pro Tabelle. Eine gespiegelte Tabelle wird in der App geändert, der sie gehört; die anderen lesen ihre Kopie. Spalten, die als von Archestack verwaltet markiert sind, sind die Ausnahme: Sie enthalten die eigenen Ergänzungen eines Teams, und ein Sync überschreibt sie nie.
• So aktuell wie der letzte Sync. Eine Tabelle wird vollständig oder nach dem synchronisiert, was sich geändert hat, und Letzteres braucht eine Spalte, die sagt, wann eine Zeile zuletzt geändert wurde, etwa modified_at.
• Verbindungen gehören zur Umgebung. Sie stehen nicht in den Dateien, jede Umgebung verbindet sich also mit ihrem eigenen Gegenstück: Abnahme mit Abnahme, Produktion mit Produktion.

Ein Repository mit einem Package pro Team wird als eine App deployt, und ein Package kann mit einem Fremdschlüssel auf die Tabelle eines anderen Packages zeigen. Ein Repository pro Team lässt jedes Team für sich ausliefern und bezahlt das mit Kopien, die nur so aktuell sind wie ihr letzter Sync.

Branches und Reviews

• Arbeite auf einem Branch und öffne einen Pull Request, wie bei jedem Code. Jeder Verweis ist ein Name, und derselbe Inhalt ergibt immer dieselben Bytes, ein Diff zeigt also nur, was jemand geändert hat: eine Zeile eines Skripts, eine Spalte, das JSX einer Page, nie eine neu nummerierte ID oder umsortierte Schlüssel.
• Einen anderen Branch auszuchecken ändert die Dateien, und das Projekt folgt ihnen, so wie es deinem Speichern folgt. Tabellenänderungen warten dann auf eine Migration; Reset Project Database fängt stattdessen mit den Tabellen des Branches neu an.
• Wer ein Review macht, checkt den Branch aus, hat ihn im eigenen Projekt laufen und führt mit Run Tests die Tests des Packages dagegen aus. Tests liegen im Package, sie wandern also mit dem Code, den sie testen.
• AGENTS.md und docs/archestack/ werden committet, der Coding-Agent jedes Entwicklers folgt also denselben Regeln.

Tabellen im Team

Eine Tabellendatei beschreibt die Struktur, die eine Tabelle haben soll, nicht die Schritte dorthin. Nach einem Pull oder einem Merge plant das Projekt jedes Entwicklers mit Add Migration seine eigene Migration aus den Tabellendateien, und die Überprüfung zeigt genau, was diese Datenbank ausführen wird, einschließlich Datenverlust und typisierter Skripte, die nicht mehr kompilieren würden. Jedes Werkzeug schreibt eine Tabellendatei in einer kanonischen Form, die Änderungen zweier Personen an derselben Tabelle kollidieren also nur dort, wo sie dasselbe ändern.

Was jede Umgebung selbst entscheidet

Wer eine Page sehen darf, was öffentlich ist, Data-API-Freigaben und API-Clients, Benutzer und Rollen, Mail-Konten, Verbindungen zu anderen Systemen und die Laufhistorie stehen nicht in den Dateien. Die Administratoren jeder Umgebung legen sie fest, ein Merge kann also nie etwas öffentlich machen oder jemandem Zugriff geben.

Test, Abnahme und Produktion werden aus dem Repository von einer Pipeline deployt, wie Deployment-Strategie beschreibt.

Einstellungen

Ein bestehendes Package hereinholen

Ein Package, das bisher nur in einem gehosteten Workspace liegt, kommt einmal ins Repository: Führe Connect to Workspace aus der Command Palette aus, melde dich an, wende Pull Package to Folder auf das Package an und wähle in der Statusleiste wieder das Projekt. Von da an ist der Ordner die Quelle, und das Projekt lässt ihn laufen. Die Tabellen des Packages kommen mit, und die Tabellen, auf die es mit einem Fremdschlüssel zeigt, sind als reine Referenz markiert, sodass das Projekt jede Tabelle anlegen kann, die das Package braucht. In einem Projekt, das schon eine Datenbank hat, warten diese Tabellen wie jede andere Tabellenänderung auf eine Migration.

Stolperfallen

• Ein Projekt startet mit leeren Tabellen. Der Ordner trägt die Struktur, nicht die Zeilen. Stammdaten aus dem Repository zu laden, gibt es noch nicht.
• Tabellen ändern sich nie beim Speichern. Nur eine deployte Migration ändert die Datenbank des Projekts, abgesehen von einem frischen Start oder einem Reset.
• Ein Reset wirft die Daten des Projekts weg. Alles andere liegt im Ordner und kommt wieder; Zeilen, die du eingegeben hast, nicht.
• Änderungen im Builder bleiben im Projekt, bis du sie in den Ordner pullst, und ein Reset verliert sie.

Wie es weitergeht

Workspaces und Hosting erklärt, wo deine App läuft, sobald sie deinen Rechner verlässt. Die Reference behandelt Packages, Script Modules und Database Deployments ausführlicher.