Archestack in VS Code

Met de Archestack-extensie voor Visual Studio Code is je app een git-repository en draait hij op je eigen machine. Open de map van de repository en de extensie start er een lokale Archestack voor: PostgreSQL, de API en de builder, uit de runtime die met de extensie wordt meegeleverd. Er is geen werkruimte om mee te verbinden en er hoeft verder niets geïnstalleerd te worden. Script modules, business events, pagina's, templates en tabellen zijn bestanden in de map, en elk bestand dat je opslaat, komt een moment later aan in de lokale Archestack.

Die lokale Archestack heet het project. Het hoort bij de repository: een teamgenoot die hem clonet, krijgt hetzelfde project, opgebouwd uit dezelfde bestanden. Werken als team beschrijft hoe de ontwikkelaars van een groter bedrijf één repository delen, en De VS Code-extensie in detail toont elk scherm.

Installeren

De extensie staat nog niet in de Visual Studio Marketplace. Ze komt als VSIX-bestand: open in VS Code de Command Palette, voer Extensions: Install from VSIX... uit en kies het bestand. Ze heeft VS Code 1.90 of later nodig.

Gebruik de Windows-build (x64). Die bevat de Archestack-runtime, de API, de builder en PostgreSQL, dus een project draait zonder dat er iets anders geïnstalleerd is. PDF's renderen in de Edge of Chrome die al op de machine staat. De universele build heeft geen runtime en draait projecten in plaats daarvan in Docker Desktop.

De extensie heeft de C#-extensie van Microsoft en de C# Dev Kit niet nodig. Haar C#-functies komen van het project zelf, en haar scripts openen in een eigen taal, dus die kunnen gewoon geïnstalleerd blijven zonder dat de twee elkaar in de weg zitten.

Een project starten

• Een nieuwe app. Open een lege map, open de view Archestack in de activiteitenbalk en kies Start project. De extensie voegt archestack.json toe, maakt een verse database aan, start de API en de builder, en logt vanzelf in als de admin van het project. New Package begint daarna de eerste packagemap.
• Een bestaande repository. Clone hem en open zijn map. Het venster start het project vanzelf: de eerste start maakt de database aan en laadt de repository in, eerst de tabellen van elke package en dan de artefacten, afhankelijkheden vóór de packages die ze nodig hebben. Een verse clone is in ongeveer vijftien seconden een werkende app, en als je het venster opnieuw opent, pakt het het project weer op.

Het project wordt beschreven in archestack.json, dat gecommit wordt:

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

De builder en de API delen webPort en PostgreSQL luistert op dbPort, allebei alleen op 127.0.0.1. De database van het project, de gegenereerde wachtwoorden en de logs staan in .archestack/project/, dat git negeert. De NuGet-packages die de scripts van het project downloaden, worden daar ook bewaard, in .archestack/project/nuget, of in een Docker-volume met de naam nuget als het project in Docker draait, zodat een herstart ze niet opnieuw downloadt.

De statusbalk toont het project als local. Vanuit de lijst ervan open je de builder van het project in de browser, stop je het project en bekijk je de logs van de API. Reset Project Database gooit de data van het project weg en laadt de repository opnieuw in.

Het project hoort bij het venster dat het draait. Het venster sluiten of herladen stopt de API en PostgreSQL, dus er blijft niets draaien, en het volgende venster start ze in enkele seconden opnieuw. Als de API niet meer antwoordt terwijl je werkt, start het venster hem binnen tien seconden opnieuw.

De repository

Een repository bevat één map per package, en een of meer bestanden per artefact:

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

Verwijzingen tussen artefacten zijn namen, nooit database-id's. Niets wat per omgeving wordt beslist, staat in de bestanden: wie een pagina mag zien, of iets openbaar is, Data API-rechten en de rungeschiedenis blijven bij elke omgeving. Dezelfde inhoud geeft altijd dezelfde bytes, dus git toont alleen echte wijzigingen.

Het project wordt vanuit de map bijgewerkt terwijl je opslaat. Een opgeslagen wijziging onder packages/ komt er een moment later aan, en wat je in de map verwijdert, wordt daar verwijderd, een hele packagemap inbegrepen. Er is niets te pushen. Tabellen zijn de uitzondering: die veranderen via migraties.

New Package begint een packagemap, en New Artifact in Package (rechtsklik op iets onder packages/ in de Explorer, of + op een package in de Workspace-view) schrijft de bestanden van een nieuw artefact. Het vraagt alleen wat het artefact nodig heeft om te bestaan, zoals de entity waar een business event bij hoort. Een nieuwe pagina is een codepagina. Een nieuw bestand met gedeelde code vraagt om zijn pad, en de bestandsextensie zegt wat het is. Add File op een artefact in de Workspace-view zet er een bestand naast: een pagina krijgt een eigen bestand naast haar views, die het importeren als ./Row, en een script module, business event of ander script, dat uit één bestand bestaat, krijgt een bestand met gedeelde code in hetzelfde package, in een map met zijn naam, dat elk script kan gebruiken.

De builder van het project werkt ook, in de browser. Een wijziging die je daar maakt, staat pas in de map wanneer je ze binnenhaalt met Pull Package to Folder, en een package die op beide plaatsen gewijzigd is, blijft ongemoeid en wordt één keer gemeld, dus er wordt niets overschreven. Commit wat je pullt zoals elke andere wijziging.

Artefacten bewerken

De code van een artefact is een bestand, en zijn instellingen zijn de JSON ernaast, die in een formulier opent. Elke wijziging in het formulier wordt in het bestand geschreven; Edit as JSON opent de tekst.

Een business entity opent in de entity-editor. De tabellen en kolommen kies je uit de database van het project, dus een naam die niet bestaat wordt gemarkeerd voordat je opslaat. De eigen instellingen van de werkruimte zijn ook bestanden, in workspace/: de branding met de logo's, en de layouts van de gepubliceerde app, die elk in een formulier openen.

C#-scripts

Script modules, scripts van business events, PDF-datascripts, scheduled events en testscripts krijgen de C#-functies van een .NET-editor. Ze worden beantwoord door de eigen compiler van het project, dus de editor ziet precies wat het script ziet wanneer het draait:

• Aanvullingen, met de signatuur en de documentatie van elk lid.
• Hover, en parameterinfo terwijl je een aanroep typt.
• Fouten en waarschuwingen terwijl je typt.
• Go to Definition (F12). Op de methode van een script module opent het het script van die module, op een parameter de instellingen die hem declareren, en op al het andere de declaraties ervan, alleen-lezen.
• Format Document, in de .NET-stijl.

De editor kent de echte scriptglobals (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc en Log), de parameters van een module als getypte variabelen, en in een business event de kolommen van de entity op Entity. Business entities zijn getypte sets op Db en script modules zijn getypte methodes op Modules, dus een hernoemde kolom of een verkeerd argument is een fout op zijn regel voordat er iets draait:

// 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 getypte sets in de referentie legt uit hoe de namen worden gevormd.

Types die in meer dan één script nodig zijn, zoals records en helpers, gaan in een gedeeld C#-bestand in de map code/ van een package. Het is gewone C#, krijgt dezelfde functies, en F12 op een van zijn types in een script opent het bestand. Shared Code in de referentie legt uit wat een gedeeld bestand kan gebruiken.

Bibliotheken van NuGet worden gedeclareerd in de nuget.json van de package, elk met een exacte versie, en hun types worden net als de rest aangevuld zodra de workspace ze heeft gedownload. Zie NuGet Packages in de referentie.

Een script module testen

Test, boven de code van een script module, voert de module uit zoals het Test-tabblad in de builder dat doet, met het script zoals de editor het heeft, bewaard of niet. Je vindt het ook in de titelbalk van de editor, bij de module in de Workspace-view en in zijn formulier. Een paneel naast het script vraagt de parameters, controleert elke waarde tegen zijn type en onthoudt ze voor de volgende keer. Een module die geen waarde nodig heeft die hij nog niet heeft, draait meteen, en Ctrl+Enter in het paneel draait hem opnieuw. Het paneel toont of de test geslaagd is, wat de module teruggaf en wat hij naar Log schreef, en bij een fout de melding met een knop naar de regel.

Een test is een proefrun: schrijfacties via Db en Files worden opgesomd in plaats van uitgevoerd, en mail en meldingen opgesomd in plaats van verstuurd, ook die van de modules die hij aanroept. Al het andere dat het script zelf doet, is echt: HTTP-aanroepen, System.IO, en alles wat een NuGet-package doet, zoals een verbinding met een andere database. Vink Show the SQL it ran aan om zijn statements in het paneel SQL Trace te zien. Alleen admins en owners kunnen testen. Een test zegt wat één run doet; een controle die elke keer draait is een testcase, zie Tests.

Pagina- en templatecode

De code van een pagina en de .tsx van een frontend template worden gecontroleerd tegen wat die code echt heeft wanneer ze draait: backend, pageContext, currentUser, de hooks, React, elke MUI-component met zijn props, de iconen, en een rijtype voor elke business entity, zoals CustomerRow. Aanvullingen, hover, fouten, go to definition, hernoemen en Format Document werken allemaal, en een return op het hoogste niveau is geen probleem. Het draait op de TypeScript die met VS Code wordt meegeleverd, dus er hoeft niets geïnstalleerd te worden.

Code kan over meerdere bestanden verdeeld worden. De eigen bestanden van een pagina staan in de paginamap naast de views en worden geïmporteerd als ./OrderRow; code die in meer dan één pagina gebruikt wordt, gaat in de map code/ van een package en wordt geïmporteerd uit @/, vanuit elke package van de repository. Imports worden gecontroleerd en getypt, go to definition volgt ze, en hernoemen past elk bestand aan dat de naam gebruikt.

What page code can use, de link boven de code van elke pagina en template, opent de volledige lijst ernaast: elke global met wat hij doet en een voorbeeld, en de rijtypes van het project. De builder toont dezelfde lijst.

Previews

Open Preview to the Side, de knop rechtsboven bij een PDF template, een frontend template, de code van een pagina of een app-layout, toont het zoals het in de editor staat, opgeslagen of niet, en volgt elke bewerking:

• Een PDF template wordt gerenderd door het project. Het datascript draait als proefrun, dus een preview schrijft nooit een rij en verstuurt nooit een mail. Parameterwaarden kun je bovenaan wijzigen.
• Een frontend template of een pagina wordt gerenderd door de eigen app van het project, met de parameters van de template of het record-id van de pagina bovenaan, en met de eigen bestanden van de pagina en de gedeelde code van de repository zoals ze in hun editors staan. Een pagina wordt getekend in de app-layout die de gepubliceerde app eromheen zet; de werkbalk wisselt naar een andere layout of naar geen.
• Een app-layout wordt getekend door de eigen shell van de gepubliceerde app, voor een pagina die je kiest.
• Een template, pagina of layout kan getoond worden op een telefoon, tablet of desktop op ware grootte, liggend of op een eigen formaat, en gezoomd tot hij past of op een percentage. De volgende preview opent op het toestel dat je het laatst koos.

Tabellen

De tabellen van een package zijn bestanden, packages/<package>/tables/<table>.json, één per tabel. Ze openen in de tabeleditor: kolommen met hun types, sleutels, defaults en foreign keys, en de indexes van de tabel. De view Database toont de tabellen van het project; Open Database Diagram tekent ze met hun foreign keys, en een tabel daar verslepen schrijft de layout.json van de package. New Table vraagt bij welke package de tabel hoort.

Een tabelbestand opslaan verandert de database van het project niet. De rest van de map gaat erin, en de Workspace-view en een melding zeggen welke tabelwijzigingen op een migratie wachten. Een verse projectdatabase, bij de eerste start of na een reset, krijgt de tabellen van de map vanzelf.

Migraties en rollback

Add Migration plant de tabelwijzigingen tegen de database van het project en toont elke operatie, het risico ervan en de exacte SQL. Operaties die data verliezen, zoals een tabel of een kolom droppen of een type versmallen, vragen dat Allow data loss aangevinkt is. De review toont ook de getypte scripts die door de wijziging niet meer zouden compileren. De migratie wordt bewaard als een openstaande deployment met een naam, voorgesteld op basis van wat er verandert, zoals AddTechnicianSkill; Deploy voert ze uit, en Add and Deploy doet beide tegelijk.

De view Deployments is de geschiedenis, nieuwste eerst. Show SQL toont wat een deployment uitvoert. Roll Back to Here plant het terugzetten van de tabellen naar wat een eerdere deployment maakte, en voegt dat toe als een eigen openstaande deployment, om te reviewen en te deployen zoals elke migratie. Een rollback herstelt structuur, nooit data: de rijen in een tabel of kolom die hij dropt, zijn weg.

Drop Table verwijdert het bestand van de tabel en markeert de tabel; hij verdwijnt wanneer een migratie met dataverlies toegestaan wordt gedeployd.

SQL-console

New SQL Query opent een SQL-editor op de database van het project, met aanvulling van tabellen en kolommen. Run Query (Ctrl+Enter) voert de selectie of het hele bestand uit, statement per statement, elk apart gecommit, en stopt bij de eerste fout. Resultaten openen naast de editor, tot 1.000 rijen elk, en zijn als CSV te kopiëren. Niets vraagt om bevestiging voor een DELETE.

Queryplannen en SQL-traces

Explain Query toont het plan dat PostgreSQL kiest voor de selectie, of voor het statement waar de cursor in staat: elke stap, wat die leest en hoeveel rijen die verwacht. Explain Analyze Query (Ctrl+Alt+Enter) voert het statement uit voor echte tijden en rijen, in een transactie die wordt teruggedraaid, dus zelfs een DELETE houdt zijn rijen. Het plan markeert de stap die de meeste tijd kost en wat een tweede blik waard is: een scan die duizenden rijen leest om er een paar te houden, een rijschatting ver van wat er terugkwam, een sortering die naar schijf moest uitwijken.

Trace SQL toont de SQL die Archestack zelf verstuurt. Rechtsklik op een script module of een business entity in de Workspace-view, of gebruik de knop op zijn bestand of formulier. Een script module draait met de parameterwaarden die je opgeeft, standaard als proefrun, waarvan de schrijfacties worden vastgelegd in plaats van uitgevoerd. Een business entity wordt gelezen zoals het grid van een pagina hem leest. Het paneel SQL Trace toont dan elk statement met zijn waarden, hoe lang het duurde en de code die het verstuurde, en kan gelijke statements samennemen om een query te tonen die één keer per rij draait. Klik op een statement om het plan te zien, het als SQL met ingevulde waarden te openen of het te kopiëren. In de view Testing doet Run with SQL Trace hetzelfde voor testcases. Alleen admins en owners kunnen tracen.

Tests

Run Tests in de Workspace-view draait de tests van elke package, van één package, een suite of een enkele case. Het project wordt eerst bijgewerkt vanuit de map, dus een case test de scripts en pagina's zoals ze in de map staan. Elke case draait in een testsandbox, een eigen database, nooit tegen de data van het project, en mail en meldingen worden vastgelegd in plaats van verstuurd. Er draaien vier cases tegelijk. Elke case toont in de boomweergave zijn laatste resultaat en hoe lang hij duurde; klik erop om te zien wat er faalde, verwacht tegenover werkelijk, en wat hij afdrukte. De view Testing toont dezelfde cases.

Een check die één onderwerp en één operator niet kunnen uitdrukken, is een codecheck: een eigen C#-bestand dat na de case draait, met Result, Output, Error en Failed bij de hand, en dat faalt wanneer het een exception gooit, een Assert niet haalt of false teruggeeft.

Event Log

De view Event Log toont wat er in het project gedraaid heeft, gegroepeerd per soort: business events, script modules, scheduled events, testruns, mail en back-ups, elk met de runs en fouten van de afgelopen dag. Een nieuwe fout wordt geteld op de badge van de view en gemeld zodra ze gebeurt. Klik op een entry om alles te lezen wat die heeft vastgelegd. Open Artifact opent het bestand van het script waarin het misging, op de regel van de fout.

Data API

Een Data API-endpoint stelt een business entity open voor andere systemen, op een adres als /api/data/v1/customers. Het hoort bij een package zoals elk ander artifact: één bestand, api/customers.json, genoemd naar zijn route en met al zijn versies erin. Het bestand opent in een formulier: de entity die het openstelt, de naam en de route, en per versie de status, de sunset-dag, de paginagrootte, de operaties en de velden. Elk veld is een publieke naam over een kolom van de entity, die teruggegeven, schrijfbaar of verplicht is; het formulier biedt de kolommen aan en markeert een veld waarvan de entity de kolom niet heeft.

Een endpoint kan ook een script module aanroepen, voor werk dat meer is dan rijen lezen of schrijven. Elke versie noemt de module en de ene methode waarop ze antwoordt, POST met de parameters in een JSON-body of GET met ze in de querystring, en somt de parameters op die aanroepers sturen: een publieke naam over een parameter van de module, verplicht of niet, met een beschrijving. Het formulier biedt de parameters van de module aan en markeert er een die de module nodig heeft maar die de versie niet doorgeeft. Een aanroeper krijgt wat de module teruggeeft, als JSON. Een module die als admin only gemarkeerd is, blijft dat: alleen admins en owners mogen haar aanroepen, dus haar endpoint krijgt geen rechten.

Een versie die gepubliceerd is, kan alleen nog groeien. Velden en operaties toevoegen mag; een veld verwijderen of hernoemen, er de schrijfrechten van afnemen, het verplicht maken of een operatie schrappen zou de systemen breken die het aanroepen. Dat hoort dus in een nieuwe versie, die het formulier begint als kopie van de getoonde. Voor een endpoint dat een script module aanroept, houdt de versie haar module en methode, en krijgt ze er alleen optionele parameters bij. Een opslag die een gepubliceerde versie breekt, wordt geweigerd, met de reden erbij. Een versie activeren biedt aan om de oudere te depreceren: die blijven bediend en vertellen aanroepers in hun headers dat ze verouderd zijn en, zodra je er een instelt, wat hun sunset-dag is, tot je ze op Retired zet.

De view Data API toont de endpoints van het project met hun versies, en zijn API clients. Try It op een endpoint of een versie stuurt echte requests en toont het antwoord zoals het binnenkwam, met de headers: als jezelf, desgewenst met de SQL die het draaide, of met de sleutel van een API client, om precies te zien wat die client mag aanroepen. Op een endpoint dat een script module aanroept, stuurt het de aanroep met voorbeeldparameters. De knoppen van de view openen het OpenAPI-document van alles wat jij mag aanroepen en How to connect, de gids voor wie erop bouwt.

Wie een endpoint mag aanroepen, beslist elke omgeving zelf en staat nooit in het bestand. Edit access in the workspace in het formulier opent de rechten: welke rollen mogen oplijsten, ophalen, aanmaken, bijwerken of verwijderen, of de module aanroepen. Een API client is een serviceaccount met rollen en een sleutel in plaats van een wachtwoord. New API Client maakt er een aan en toont zijn sleutel één keer; Rotate Key vervangt hem, en de oude sleutel werkt meteen niet meer.

Coding agents

De repository vertelt coding agents zoals Claude Code en Codex wat ze erin kunnen maken, zoals de MCP Server dat aan een verbonden model vertelt. New Package en elke pull schrijven:

• AGENTS.md: hoe een wijziging de app bereikt, de regels die elk bestand volgt, de fouten die je moet vermijden en een voorbeeld van elke soort artefact. Alleen het gemarkeerde deel van de extensie wordt herschreven, dus de eigen notities van je team in het bestand blijven staan.
• CLAUDE.md, dat Claude Code naar AGENTS.md verwijst.
• docs/archestack/: de script- en testgidsen en wat paginacode kan gebruiken. Het wordt gecommit, dus een agent die op een verse clone werkt, heeft ze ook.
• .archestack/context/: de business entities van het project en zijn gegenereerde datamodel, alleen voor deze machine.

Update Agent Instructions schrijft ze opnieuw. De bewerkingen van een agent zijn opgeslagen bestanden zoals de jouwe, dus ze bereiken het project op dezelfde manier; een mens reviewt en commit ze.

Werken als team

Voor een groter bedrijf is de repository de bron van waarheid van de applicatie, zoals infrastructure as code servers beschrijft: alles waaruit de app bestaat, is een bestand in git, gereviewd en geversioneerd zoals elke andere code, en elke omgeving wordt uit die bestanden opgebouwd. Met de extensie werkt elke ontwikkelaar eraan.

Ontwikkelaar 1

Repositorybestanden Lokaal project

Ontwikkelaar 2

Repositorybestanden Lokaal project

Ontwikkelaar 3

Repositorybestanden Lokaal project

push en pull

Git-server

De repository: branches, pull requests en main

Pipeline

Bouwen, testen, plannen, deployen

Test

Gehoste Archestack

Acceptatie

Gehoste Archestack

Productie

Gehoste Archestack

Elke ontwikkelaar draait een eigen kopie

Elke ontwikkelaar clonet de repository en opent hem, en dat venster draait een eigen project, met een eigen database, op de eigen machine. Niemand deelt een ontwikkelwerkruimte, dus niemand slaat iets op over het werk van een ander, en een script dat kapotgaat, blijft op één machine tot het gerepareerd is. Een nieuw teamlid heeft de app ongeveer vijftien seconden na de clone draaien. De tabellen van een project beginnen leeg, en testcases schrijven de rijen die ze nodig hebben in hun eigen sandbox, dus elke ontwikkelaar test tegen dezelfde data.

Eén package per team

Een grote app bestaat uit meerdere packages, elk een map met eigen tabellen, business entities, pagina's, scripts en tests. Deel ze op zoals het bedrijf opgedeeld is, en teams werken grotendeels in eigen mappen:

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

Een package noemt de packages die hij nodig heeft in zijn package.json, met naam en versiebereik:

{
  "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": []
}

Een kale versie zoals 2.0 betekent die versie of nieuwer, [2.0] precies die ene, en [2.0,3.0) alles vanaf 2.0 tot 3.0, maar niet 3.0 zelf. Een project laadt afhankelijkheden vóór de packages die ze nodig hebben. Een tabel die van een andere package is, wordt alleen ter referentie meegenomen: een package kan er een foreign key naar laten wijzen, maar verandert hem nooit. Met de code owners-functie van je git-host kun je dan voor elke map een review verplicht maken door het team dat er eigenaar van is.

Of een repository per team

Teams die ook op hun eigen moment moeten kunnen releasen, kunnen in plaats daarvan elk een eigen repository hebben, en daarmee een eigen app, een eigen project en eigen omgevingen. De data die het ene team bezit en het andere nodig heeft, bereikt dat andere team als third-party-tabellen: de omgevingen van dat team verbinden met de database van het team dat eigenaar is en spiegelen de tabellen die ze nodig hebben, volgens een schema. Een gespiegelde tabel leest als elke andere tabel van de app, in business entities, pagina's en scripts.

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

• Eén eigenaar per tabel. Een gespiegelde tabel wordt gewijzigd in de app die er eigenaar van is; de andere lezen hun kopie. Kolommen die als "managed by Archestack" gemarkeerd zijn, vormen de uitzondering: die bevatten de eigen aanvullingen van een team, en een sync overschrijft ze nooit.
• Zo vers als de laatste sync. Een tabel synct volledig of alleen wat er veranderd is, en dat laatste vraagt een kolom die zegt wanneer een rij voor het laatst veranderde, zoals modified_at.
• Verbindingen horen bij de omgeving. Ze staan niet in de bestanden, dus elke omgeving verbindt met haar eigen tegenhanger: acceptatie met acceptatie, productie met productie.

Eén repository met een package per team deployt als één app, en een package kan een foreign key laten wijzen naar een tabel van een andere package. Een repository per team laat elk team op zijn eigen moment releasen, en betaalt daarvoor met kopieën die maar zo vers zijn als hun laatste sync.

Branches en reviews

• Werk op een branch en open een pull request, zoals bij elke code. Elke verwijzing is een naam en dezelfde inhoud geeft altijd dezelfde bytes, dus een diff toont alleen wat iemand veranderd heeft: een regel van een script, een kolom, de JSX van een pagina, nooit een hernummerd id of sleutels in een andere volgorde.
• Een andere branch uitchecken verandert de bestanden, en het project volgt ze zoals het je opgeslagen wijzigingen volgt. Tabelwijzigingen wachten dan op een migratie; Reset Project Database begint in plaats daarvan opnieuw vanaf de tabellen van de branch.
• Een reviewer checkt de branch uit, laat hem draaien in een eigen project en draait er de tests van de package tegen met Run Tests. Tests staan in de package, dus ze reizen mee met de code die ze testen.
• AGENTS.md en docs/archestack/ worden gecommit, dus de coding agent van elke ontwikkelaar volgt dezelfde regels.

Tabellen in een team

Een tabelbestand beschrijft de structuur die een tabel moet hebben, niet de stappen om daar te komen. Na een pull of een merge plant het project van elke ontwikkelaar zijn eigen migratie uit de tabelbestanden met Add Migration, en de review toont precies wat die database zal uitvoeren, dataverlies en getypte scripts die niet meer zouden compileren inbegrepen. Elke tool schrijft een tabelbestand in één canonieke vorm, dus de bewerkingen van twee mensen aan dezelfde tabel conflicteren alleen waar ze hetzelfde veranderen.

Wat elke omgeving zelf beslist

Wie een pagina mag zien, wat openbaar is, Data API-rechten en API clients, gebruikers en rollen, mailaccounts, koppelingen met andere systemen en de rungeschiedenis staan niet in de bestanden. De beheerders van elke omgeving stellen ze in, dus een merge kan nooit iets openbaar maken of iemand toegang geven.

Test, acceptatie en productie worden vanuit de repository door een pipeline gedeployd, zoals Deploymentstrategie beschrijft.

Instellingen

Een bestaande package binnenhalen

Een package die tot nu toe alleen in een gehoste werkruimte staat, komt één keer de repository in: voer Connect to Workspace uit vanuit de Command Palette, log in, gebruik Pull Package to Folder op de package, en kies het project weer in de statusbalk. Vanaf dan is de map de bron en draait het project hem. De tabellen van de package komen mee, met de tabellen waar hij met een foreign key naar verwijst gemarkeerd als alleen ter referentie, zodat het project elke tabel kan maken die de package nodig heeft. In een project dat al een database heeft, wachten die tabellen op een migratie zoals elke andere tabelwijziging.

Valkuilen

• Een project begint met lege tabellen. De map bevat de structuur, niet de rijen. Stamgegevens laden vanuit de repository is nog niet gebouwd.
• Tabellen veranderen nooit bij het opslaan. Alleen een gedeployde migratie verandert de database van het project, afgezien van een verse start of een reset.
• Een reset gooit de data van het project weg. Al het andere staat in de map en komt terug; rijen die je hebt ingevoerd niet.
• Wijzigingen in de builder blijven in het project tot je ze in de map pullt, en bij een reset gaan ze verloren.

Waar dit naartoe gaat

Werkruimtes en hosting legt uit waar je app draait zodra hij je machine verlaat. De referentie behandelt packages, script modules en database-deployments uitgebreider.