Creating Revision Drafts

A revision draft is the starting point for proposing and managing architectural changes within your Architect-driven project. It's essentially a structured plan, typically defined in a JSON file (commonly named revisions.json), that outlines the modifications you intend to make.

Structure of a Revision Draft

At its core, a revision draft is a JSON array consisting of one or more ComponentOperation objects. Each ComponentOperation describes a single atomic change to a component in your system.

Key fields within a ComponentOperation object include:

• name: (String) The unique name of the component being affected (e.g., UserDTO, OrderAggregate, create_user_endpoint).
• component_type: (String) The type of the component (e.g., dto, aggregate, api_endpoint, domain_event, permission). This corresponds to the component types managed by Architect.
• operation_type: (String) The action to be performed. Common values are:
  • CREATE: Create a new component. (Equivalent to ADD in some contexts)
  • UPDATE: Modify an existing component.
  • DELETE: Delete a component. (Equivalent to REMOVE in some contexts)
• definition: (Object) A JSON object representing the full definition of the component. This is primarily used for ADD and UPDATE operations. The structure of this object depends on the component_type.
• context_kwargs: (Object, Optional) A dictionary providing additional context for the operation, which can influence how and where the component is generated or modified. Common keys include:
  • bounded_ctx: The name of the bounded context the component belongs to.
  • version: An API version (e.g., v1, v2) if applicable.
  • Other component-specific context.

Example ComponentOperation:

{
  "name": "UserProfileDTO",
  "component_type": "dto",
  "operation_type": "CREATE",
  "definition": {
    "name": "UserProfileDTO",
    "description": "Data Transfer Object for user profile information.",
    "fields": [
      {"name": "user_id", "type_str": "uuid.UUID", "is_optional": false},
      {"name": "username", "type_str": "str", "is_optional": false},
      {"name": "email", "type_str": "str", "is_optional": false},
      {"name": "bio", "type_str": "str", "is_optional": true}
    ]
  },
  "context_kwargs": {
    "bounded_ctx": "identity_access",
    "version": "v1"
  }
}

How to Create Revision Drafts

1. Manually: You can create or edit a revisions.json file by hand, carefully crafting each ComponentOperation object according to your architectural needs. This gives you precise control but can be time-consuming for larger changes.

2. With LLM Assistance (Recommended for Complex Changes):

   • Generate Context: First, ensure your project's context is up-to-date by running:

     architect context combine-for-llm -o .vscode/architect-context.json

     (Replace .vscode/architect-context.json with your preferred path).
   • Prompt the LLM: Provide the content of your architect-context.json to a Large Language Model. Clearly describe the new feature, modification, or refactoring you want to achieve. Ask the LLM to generate the necessary ComponentOperation objects for your revisions.json file.
   • Review and Refine: Carefully review the LLM-generated operations. LLMs are powerful aids, but the generated output should always be validated and refined by a human developer to ensure correctness, completeness, and adherence to your project's specific conventions.

Next Steps

Once you have a revision draft, the next steps typically involve:

• Understanding the details of various Component Operations (Link to be created).
• Applying Revisions to your codebase (Link to be created).