Skip to main content

Architect: Revision Workflows

This document outlines the revision and scaffolding workflows for the architect tool, distinguishing between a local "Single User Mode" and a more controlled "Collaboration Mode" designed for team environments.

Single User Mode​

This mode is optimized for individual developers or small, trusted teams working locally. It prioritizes speed and rapid iteration.

Target Environment: Local developer machine.

Authentication:

  • No authentication is enforced (AUTHORIZATION_ENGINE: allow_all).
  • The developer has full control to perform all actions.

Revision Workflow:

  • The workflow is direct and implicit. Developers can:
    • Create revision drafts.
    • Approve their own drafts.
    • Apply revisions immediately.
  • The distinction between draft, approved, and applied states is primarily for the developer's own organization or if they choose to simulate a more formal process locally.

Scaffolding (Code Generation):

  • Scaffolding happens dynamically and directly on the local filesystem.
  • When a revision is applied, the architect tool generates or modifies code in the COMPONENTS_BASE_PATH (which is typically bind-mounted to the developer's local project directory, e.g., ..:/data in the .devcontainer/compose.yaml).
  • Changes are immediately visible and testable.

architect CLI Usage:

  • The CLI can be used for all operations: creating, approving, applying revisions, and triggering scaffolding.

Database:

  • Typically uses a local SQLite database (as seen in .devcontainer/compose.yaml), with migrations applied automatically on startup.

Key Characteristics:

  • Frictionless development.
  • Immediate feedback.
  • Full control for the developer.

Collaboration Mode​

This mode is designed for teams, production-like environments, and scenarios requiring more control, review, and auditable changes. It integrates with a GitOps-style workflow.

Target Environment: Shared environments like Cloud instances, VMs, or Kubernetes clusters.

Authentication & Authorization:

  • A robust authentication and authorization mechanism is intended (e.g., OIDC with Casbin for role-based access control, as indicated by commented-out environment variables in deploy/compose.yaml).

  • Permissions:

    • Domain Experts/Developers: Can create and manage "Revision Drafts" within the architect UI. They can experiment with component configurations.
    • Authorized Developers/Reviewers: Have permissions to "Approve" revision drafts, promoting them to an "Approved Revision" state.
    • CI/CD System (or highly privileged users): Is responsible for "Applying" an approved revision, which triggers the actual code generation and deployment process.

Revision Workflow (Explicit & Controlled):

  1. Draft Revision:

    • Users interact with the architect UI to define a set of changes to components.
    • These changes are saved as a "Revision Draft" (a JSON array of ComponentOperation). This draft is stored in the architect application's database (PostgreSQL).
    • At this stage, no code is generated in the primary codebase.

  2. Approved Revision:

    • A draft revision undergoes a review process (manual or defined by team policy).
    • An authorized user approves the draft, transitioning it to an "Approved Revision" state within the architect application.

  3. Apply Revision (CI/CD Driven Scaffolding):

    • Scaffolding does not happen dynamically within the running architect application's COMPONENTS_BASE_PATH in this mode.

    • The "Approved Revision" (as a JSON object) is the key artifact that triggers the scaffolding process. This JSON can be:

      • Downloaded from the architect UI/API.
      • Passed to a CI/CD pipeline.

    • CI/CD Pipeline Responsibility:

      • Checks out the target application's Git repository.
      • Uses the architect CLI, providing the downloaded JSON revision as input.
      • The CLI generates/modifies code based on the revision within the CI pipeline's workspace (which is a clone of the target repository).
      • The CI pipeline commits these generated changes to a new branch in the target application's repository.
      • A pull/merge request is created for further review by the development team.
      • Once merged into the main development or release branch, this becomes the new "base state."

    • COMPONENTS_BASE_PATH (/data in the container):

      • When the architect application starts in Collaboration Mode (as per deploy/entrypoint.py), it clones a specific branch (e.g., main or a release branch) from a designated Git repository (GIT_REPO_URL_FOR_COMPONENTS) into its /data directory.
      • This /data directory represents the current "live" or "base" state of the components, reflecting the last successfully applied and merged revision.
      • The architect application treats this path as read-only for its UI operations when users are creating new drafts. Drafts are simulated against this base state.

    • Key Benefits of JSON Revisions:

      • Portability: Revisions are self-contained JSON documents.
      • Local Application: Developers can download an approved revision JSON and apply it locally using the architect CLI to test its impact or make further manual refinements before committing.
      • CI Automation: CI pipelines can consume these JSON revisions to automate scaffolding.
      • Iterative Improvement: A revision applied locally can be manually enhanced, and the resulting code (not the JSON revision itself, but the scaffolded code) can be committed and pushed to Git, potentially forming the basis for a new iteration or a new revision draft.

    • Database:

      • Uses a persistent, shared database like PostgreSQL to store revision drafts, approved revisions, component definitions, and other application states. Migrations are run by the entrypoint.py script on startup.

    • Key Characteristics:

      • Controlled changes with clear review gates.
      • GitOps-friendly: Code generation is tied to the Git workflow.
      • Auditability of changes through Git history and revision states.
      • Separation of concerns: UI for drafting, CI for scaffolding.
      • Domain experts can contribute to defining component structures without directly writing production code.