Explain the software architecture

A process map shows how work moves. A software architecture shows the systems that support that work, their responsibilities, and their connections. A legal engineering design usually needs both.

An activity labeled “record the review” leaves technical questions open. Which system owns the record? What information crosses the boundary? What happens when the repository is unavailable? Who can retrieve the result?

Choose a view for the question

The C4 approach provides successive views of a software system: context, containers, components, and code. “Container” here means an application or data store, not necessarily a Docker container.

View the relationship model

flowchart TB
    C1["CONTEXT<br/>People, the system, and external systems"] --> C2["CONTAINERS<br/>Applications and data stores inside the boundary"]
    C2 --> C3["COMPONENTS<br/>Responsibilities within an application"]
    C3 --> C4["CODE<br/>Implementation detail where it helps"]

Use the level that resolves the uncertainty. A partner discussing a research service may need a context view. A developer planning checkpoint import needs to know which component validates state and which store owns it. Drawing all four levels for every feature creates documents that can be harder to maintain than the system.

The local workflow system

The following is a conceptual container-level view of this toolkit's local execution arrangement. It shows responsibility and data movement rather than a deployment to a cloud service.

View the relationship model (Mermaid)

flowchart TB
    L["Lawyer or operator"] --> H["Active AI host<br/>Conversation, reasoning, connected tools"]
    H -->|Structured commands and task results| R["Python workflow runner<br/>Validate, route, and checkpoint"]
    R -->|Persist transitions| D[("SQLite run state")]
    R -->|Read pinned definitions| P["Manifest and skill packages"]
    H -->|Authorized tool use| E["External systems<br/>Research sources or repository"]
    E -->|Evidence and receipts| H
    R -->|Eligible task or waiting state| H

The runner owns workflow state. The host supplies the available model and tools. External services have their own access requirements and failure modes. A connection shown in an architecture diagram is not evidence that access has been configured.

Describe interactions as well as structure

A sequence view can show how a task moves between participants over time. It helps identify where validation, failure, and review happen.

View the relationship model

sequenceDiagram
    participant H as Active host
    participant R as Runner
    participant T as Connected tool
    H->>R: Request next eligible task
    R-->>H: Scoped task envelope
    H->>T: Perform authorized task
    T-->>H: Result and evidence
    H->>R: Submit structured result
    R->>R: Validate identifiers and output
    R-->>H: Advance or explain blocked state

The sequence is simplified. A tool call with an uncertain external outcome needs reconciliation, and a designated human decision requires a separate recorded decision. Those cases belong in the detailed design and tests.

Record consequential decisions

An architecture decision record explains the context, options, chosen approach, and consequences of a decision. Keep it short and versioned.

For example, choosing local SQLite may make a first release portable and easy to inspect. It also sets a boundary: a local audit record does not provide independently verified enterprise identity, and copied checkpoints need explicit lineage handling. Recording the tradeoff makes later changes easier to assess.

AI can draft diagrams from code and notes, but it may miss an external dependency, invent a boundary, or describe intended behavior instead of actual behavior. Review every view against the system and keep its source editable.