Skip to main content

UI Overview

The Castlecraft Architect UI provides a visual interface for interacting with your project's architecture, managing components, and orchestrating changes through the revision system. It is designed to cater to different operational needs, primarily distinguished by "Single User Mode" and "Collaboration Mode."

The UI is a web application (typically built with React) that communicates with the Architect backend via its REST APIs (primarily the /api/v1/... endpoints).

Common UI Features​

Regardless of the mode, the UI generally aims to provide:

  • Component Visualization: A way to view the currently defined components in your project (e.g., aggregates, DTOs, services, repositories).
  • Revision Draft Creation: Tools to create new "Revision Drafts" by adding, modifying, or removing components.
  • Component Configuration: Forms and editors to define the properties and relationships of components within a draft.
  • State Management: Displaying the current state of components and the proposed changes within a revision draft.

UI in Single User Mode (Local Development)​

In Single User Mode, the UI is optimized for individual developers or small, trusted teams working locally, prioritizing speed and direct control.

Key Characteristics & UI Interactions:

  • Direct Control: The developer has full control. Authentication is typically disabled (AUTHORIZATION_ENGINE: allow_all).
  • Rapid Iteration:
    • Users can create revision drafts.
    • They can directly "approve" their own drafts through the UI.
    • They can "apply" revisions, triggering immediate code generation on their local filesystem (via the bind-mounted COMPONENTS_BASE_PATH).
  • Immediate Feedback: Changes made by applying a revision are instantly reflected in the local codebase, allowing for quick testing and further iteration.
  • Visualization of Local State: The UI reflects the state of components based on the local COMPONENTS_BASE_PATH.
  • Database: Revision drafts and other UI-managed states are typically stored in a local SQLite database.

The UI in this mode acts as a powerful local scaffolding assistant, allowing developers to visually design and apply architectural changes quickly.

UI in Collaboration Mode (Team/GitOps Workflow)​

In Collaboration Mode, the UI facilitates a more controlled, team-oriented workflow, often integrated with GitOps practices.

Key Characteristics & UI Interactions:

  • Role-Based Access: The UI respects the configured authentication and authorization system (e.g., OIDC with Casbin). Different users will have different capabilities based on their roles:
    • Domain Experts/Developers: Can create and manage "Revision Drafts." They use the UI to define desired architectural changes.
    • Authorized Reviewers: Can "Approve" revision drafts, promoting them to an "Approved Revision" state. This action is typically restricted.
  • Separation of Concerns:
    • Drafting: The UI is the primary tool for drafting revisions. These drafts are stored in a shared, persistent database (e.g., PostgreSQL).
    • Applying: The UI typically does not directly apply revisions to generate code in the live application environment. Instead, an "Approved Revision" is usually downloaded (as a JSON file) from the UI or API.
  • GitOps Integration:
    • The downloaded JSON revision is then fed into a CI/CD pipeline.
    • The CI/CD pipeline uses the architect CLI to apply this revision to a checked-out version of the application's Git repository, commits the changes, and creates a pull/merge request.
  • Visualization of Base State: When users create new drafts, the UI visualizes the component state based on a "base" version of the codebase, typically cloned from a specific Git repository branch (defined by GIT_REPO_URL_FOR_COMPONENTS) into the Architect application's /data directory. This directory is treated as read-only for UI drafting operations.
  • Managing Revision Lifecycle: The UI allows users to view the status of drafts (e.g., Draft, Approved, Rejected) and participate in the review/approval process according to their permissions.

The UI in this mode serves as a collaborative design and governance tool, enabling teams to define and review architectural changes before they are programmatically applied and integrated into the codebase via a CI/CD and Git workflow.

Future Enhancements​

The UI is an evolving part of Castlecraft Architect. Future enhancements may include:

  • More sophisticated visual modeling tools.
  • Deeper integration with LLM-assisted component design.
  • Enhanced dashboards for tracking revision history and impact.