Taxonomy Architecture Analyzer：AI 辅助的架构原型分析工具

Taxonomy Architecture Analyzer

Generate plausible, traceable architecture prototypes from requirements—rapidly, with AI assistance and human control.

Taxonomy Architecture Analyzer uses hierarchical AI-assisted analysis to turn requirements, regulations, and source documents into plausible cross-layer architecture prototypes. It traverses the architecture catalogue, scores relevant paths, proposes elements and relations, and produces inspectable views and exportable models.

The primary goal is to shorten the path from an unstructured need to a useful first architecture model by automating much of the initial catalogue analysis and model construction. The result is deliberately a prototype rather than an authoritative decision: scores, rationales, source mappings, proposals, and accepted changes remain reviewable, attributable, comparable, refinable, versioned, and reversible.

By externalizing taxonomy paths, scores, relations, provenance, and history, the workbench also reduces the amount of architecture context users must reconstruct and keep in mind at once.

Taxonomy addresses architecture work in federal, state and local public administration and in enterprises. Example scenarios describe test coverage, not a restriction of the intended users or application domains.

Why use Taxonomy?

Taxonomy connects architecture prototyping with requirement clarification: inspect a proposed architecture, work through evidence-linked decision questions, review a separate wording proposal, and explicitly adopt a new requirement draft. A separately requested analysis can then use that draft and its inherited decisions. The original text and earlier analysis remain available; generated wording is not silently treated as an approved requirement or an accepted architecture change.

The value is the connected workflow, not a claim that AI, Git, or diagrams are exclusive to this product:

• Clarify the need: bottom-up formulations and cross-taxonomy review connect wording and decision questions to the selected architecture evidence.
• Retain the reasons: saved proposals and historical exports retain the source, snapshot and decisions used at that time instead of reinterpreting them against today's catalogue.
• Control the work: choose taxonomy roots and full or taxonomies-only analysis; distinguish completed, excluded and unresolved work, and reuse validated answers when resuming a compatible run.

Start with the browser workflows in the English user guide or German user guide. The reformulation contract and verification boundaries describe what is implemented and what has not been established by live-model evaluation.

What the application provides

Typical workflow

flowchart LR
    A[Requirement or source document] --> B[Candidate extraction]
    B --> C[AI-assisted hierarchical analysis]
    C --> D[Architecture prototype]
    D --> E[Human architecture review and refinement]
    E --> F[Explicit versioned architecture change]
    F --> G[Diagram, report, or data export]
    D --> H[Separate wording proposal and decision questions]
    H --> I[Human answers, edits and adoption review]
    I --> J[Explicit adoption as a new requirement draft]
    J -->|separately request a new analysis| C

Loading

AI-generated scores, relations, and architecture prototypes are proposals, not authoritative decisions. Users remain responsible for reviewing rationales, source mappings, and model content before accepting them.

Adoption does not automatically run another analysis or modify the architecture. Completing the planned work does not prove semantic completeness. Technical tests and retained evidence do not establish superior results against another product. Local ONNX cannot complete generative relationship assessment or wording synthesis.

Portable backup/history/restore work is still being integrated; it is not a released end-to-end backup or round-trip contribution workflow merely because supporting capture adapters exist. Check the exact deployed version and documented support boundary before relying on it.

Architecture Impact Showcase

The following view is generated by the real architecture-view and Mermaid export pipeline for an integrated hospital communication requirement. A drift-prevention test compares this block with current exporter output.

flowchart TD
    subgraph Capabilities["🔵 Capabilities"]
        CP_1023(["Communication and Information System Ca…<br/>★ ⚠ 85%"])
    end
    subgraph Business_Roles["🟢 Roles"]
        BR["Business Roles<br/>61%"]
    end
    subgraph Business_Processes["🟢 Processes"]
        BP_1490["Health Services<br/>58%"]
    end
    subgraph Core_Services["🟠 Core Services"]
        CR_1047(["Infrastructure Services<br/>★ 75%"])
    end
    subgraph COI_Services["🟠 COI Services"]
        CI["COI Services<br/>74%"]
    end
    subgraph User_Applications["🟣 Applications"]
        UA_1574["Unified Communication Applications<br/>62%"]
    end
    subgraph Communications_Services["🔴 Communications"]
        CO_1011(["Communications Access Services<br/>★ ⚠ 80%"])
        CO_1050["Transit Services<br/>55%"]
    end
    CP_1023 -->|realizes| CO_1011
    CP_1023 -->|realizes| CR_1047
    CO_1011 -->|supports| CR_1047
    CR_1047 -->|fulfills| CP_1023
    CO_1011 -->|depends on| CR_1047
    CR_1047 -->|supports| UA_1574
    UA_1574 -->|uses| CR_1047
    UA_1574 -->|uses| CO_1011
    CR_1047 -->|supports| BP_1490
    UA_1574 -->|supports| BP_1490
    CO_1011 -->|supports| BP_1490
    CP_1023 -->|realizes| CO_1050
    classDef cap fill:#4A90D9,color:#fff,stroke:#2171B5
    classDef proc fill:#27AE60,color:#fff,stroke:#1E8449
    classDef role fill:#27AE60,color:#fff,stroke:#1E8449
    classDef svc fill:#F39C12,color:#fff,stroke:#D68910
    classDef app fill:#8E44AD,color:#fff,stroke:#6C3483
    classDef info fill:#3498DB,color:#fff,stroke:#2980B9
    classDef comm fill:#E74C3C,color:#fff,stroke:#C0392B
    classDef hotspot fill:#D32F2F,color:#fff,stroke:#B71C1C,stroke-width:3px
    class CP_1023 cap
    class CP_1023 hotspot
    class BR role
    class BP_1490 proc
    class CR_1047 svc
    class CI svc
    class UA_1574 app
    class CO_1011 comm
    class CO_1011 hotspot
    class CO_1050 comm

Loading

Legend: ★ = direct match · ⚠ = impact hotspot (≥ 80%) · rounded nodes = anchors/hotspots · percentages = relevance score · arrow labels = relation type

Quick start

Requirements

• Java 21
• Docker for integration and browser verification profiles
• Git

Use the checked-in Maven Wrapper. A separately installed Maven version is neither required nor recommended.

git clone https://github.com/carstenartur/Taxonomy.git
cd Taxonomy
./mvnw -pl taxonomy-app -am spring-boot:run

Open http://localhost:8080.

On a new local database, the application creates the admin account with a random one-time bootstrap password in a uniquely named owner-only temporary file. The startup log contains only the file path. Read the file once, sign in, and replace the password immediately; the application removes the file after the committed administrator password change. No reusable password is published in this repository.

To provide the initial password explicitly for local development:

export TAXONOMY_ADMIN_PASSWORD='use-a-unique-local-development-secret'
./mvnw -pl taxonomy-app -am spring-boot:run

To browse without loading or downloading the embedding model:

export TAXONOMY_EMBEDDING_ENABLED=false
./mvnw -pl taxonomy-app -am spring-boot:run

The local command starts plain HTTP on port 8080. Do not expose that port directly to the internet.

Production deployment

The supported production example places Caddy in front of the application, enables automatic HTTPS, keeps application port 8080 inside the Docker network, and stores application state in named volumes.

cp .env.example .env
# Configure DOMAIN, TAXONOMY_ADMIN_PASSWORD, and optional provider settings.
docker compose -f docker-compose.prod.yml up -d --build

In local-user mode, production startup rejects missing, placeholder, or short administrator passwords. Keycloak mode has separate identity-provider configuration requirements. Review the complete deployment and security documentation before exposing an instance outside a trusted development machine.

• Deployment guide
• Deployment checklist
• Container image
• Security
• Configuration reference

Build and verification

Fast default verification:

./mvnw verify

Canonical Maven CI profile, including integration, browser, quality, coverage, and local ONNX suites:

./mvnw -B verify -Pci -DrunOnnxTests=true

Full reproduction of every required CI check with only Java and Maven installed is not yet achieved. The remaining runtime and lifecycle gaps are documented in Maven Verification Authority.

Focused profiles include:

./mvnw test -Parchitecture-tests -Dsurefire.failIfNoSpecifiedTests=false
./mvnw verify -Pdocument-import-tests
./mvnw verify -Parchimate-import-tests
./mvnw verify -Pdatabase-postgres
./mvnw verify -Ponnx
./mvnw verify -Pui-tests

Without Docker, use the same Spring Boot/HSQLDB scenarios and GUI checks with matching local Chrome and ChromeDriver binaries:

CHROME_BIN=/absolute/path/chrome CHROMEDRIVER=/absolute/path/chromedriver ./mvnw verify -Ptest-local

See Docker-free tests and GUI preview for focused runs, screenshots and the coverage retained in the existing CI profiles.

The whole-repository module-extraction gate is owned by taxonomy-build, which is ordered after the application, aggregate coverage, and tooling modules. It runs in ordinary full-reactor verification and in the root-level architecture-tests profile. Focused selections that end at taxonomy-app, including the Keycloak-only lane, do not run this whole-reactor inventory; the full reactor remains its enforcement boundary.

The build generates:

• JUnit and Failsafe reports
• aggregate JaCoCo coverage
• browser and accessibility evidence
• CycloneDX SBOM files
• dependency-alignment and supply-chain policy reports

Taxonomy is a modular monolith with one deployable Spring Boot application. The Maven reactor contains twenty child modules: six framework-free foundations, a plugin runtime, an external plugin, eight runtime feature libraries, the application composition root, and three build/tooling modules.

How the application fits together

This is Taxonomy's own application architecture, not an architecture model produced by the workbench. Arrows describe logical collaboration, not a complete Maven dependency graph. All internal groups run in the same Spring Boot application.

flowchart TB
    Browser["Browser / REST client"] --> App["Application composition<br/>HTTP, security, scope resolution"]
    App --> Portfolio["Portfolio and analysis<br/>Requirements, jobs, review snapshots"]
    Portfolio --> Knowledge["Knowledge<br/>Catalogue, relations, search"]
    Portfolio --> Architecture["Architecture<br/>Derivation, diagrams, reports"]
    App --> Workspace["Workspace and editor<br/>Semantic journal, explicit Git checkpoints"]
    App --> Interop["Interoperability<br/>Reviewed external exchanges"]
    Interop --> Workspace
    Architecture --> Delivery["Templates and export<br/>Validated templates, neutral codecs"]
    Portfolio -.->|optional provider calls| AI["External LLM provider"]

Loading

The architecture guide (Deutsch) separates feature-module dependencies, the requirement workflow, and persistence responsibilities. It distinguishes immutable analysis snapshots, editable workspace revisions, the durable semantic journal, and explicit Git checkpoints.

Module inventory

Feature libraries do not depend back on taxonomy-app; the runtime module dependency graph is acyclic. The supporting preferences and provenance contexts deliberately remain in the application for now. This split does not introduce microservices or claim that every internal package cycle has been removed.

Owned unit tests move with each feature library. Cross-context application, database, security, and recovery tests remain with the application. Maven/architecture checks enforce module ownership and dependency direction; packaging checks verify the feature libraries, unique runtime classes/resources, and application-owned migrations in the executable JAR.

See the module boundaries (Deutsch) and the #628 completion scope for the detailed ownership and verification contracts.

Important implementation choices:

• Java 21 and Spring Boot
• Hibernate ORM and Hibernate Search
• Lucene full-text and vector indexes
• JGit-backed architecture history
• database-backed logical Git repositories through jgit-storage-hibernate
• DJL and ONNX Runtime for optional local embeddings
• Thymeleaf-based web UI
• Testcontainers for reproducible external-system integration tests
• Playwright for cross-browser and accessibility verification

See Architecture for component boundaries and Repository topology for workspace and shared-repository behavior.

Architecture history and collaboration

Accepted semantic editor operations are durable revisions with their own audit and undo/redo history. They are not one Git commit per operation. A Git commit is an explicit, stable checkpoint; an immutable analysis/workbench snapshot is a separate result selected for review or snapshot-bound export.

Architecture content is stored as a purpose-built textual DSL rather than as opaque serialized UI state. This enables:

• human-readable review
• semantic and textual comparison
• named variants
• shared and personal workspaces
• merge and conflict detection
• revert and restoration
• selective transfer of individual changes
• traceability from source material to accepted architecture content

External canonical repositories can be integrated through JGit transport. Synchronization uses commit ancestry and three-way merge semantics; rejected pushes and merge conflicts are reported instead of being presented as success.

See Git integration and Workspace and versioning guide.

Document import and provenance

PDF and DOCX processing is bounded by upload size, PDF page count, expanded archive size, extracted text length, and candidate count. ZIP-bomb checks are performed before Apache POI expands DOCX content.

Document registration and candidate confirmation are transactional. A failed operation does not leave a partially created provenance graph, and repeating the same candidate confirmation is idempotent.

AI and local operation

For the actual grouping criteria, score calculations, limitations and rationale for each of the eight sub-taxonomies, see Grouping and scoring (Deutsch). It separates implemented arithmetic, remaining navigation/provenance restrictions, and relevance from necessity.

The application can use Gemini, OpenAI-compatible providers, or a local ONNX embedding model. Provider configuration is optional for catalogue browsing, DSL editing, version navigation, deterministic validation, and many search and export functions.

Local embedding configuration:

export LLM_PROVIDER=LOCAL_ONNX
export TAXONOMY_EMBEDDING_ENABLED=true
export TAXONOMY_EMBEDDING_MODEL_PROFILE=MULTILINGUAL_MINILM_L12
export TAXONOMY_EMBEDDING_MODEL_DIR=/absolute/path/to/multilingual-minilm
export TAXONOMY_EMBEDDING_ALLOW_DOWNLOAD=false

The default local model supports German and English retrieval. Provision its pinned files with .github/scripts/download-embedding-model.sh; inference can then run offline. Existing BGE installations must explicitly select TAXONOMY_EMBEDDING_MODEL_PROFILE=BGE_SMALL_EN. See model provisioning and migration.

For deployment provenance and model-policy details, see:

• AI transparency
• Digital sovereignty
• Data protection

Security model

The application supports local form login and a Keycloak/OIDC profile. Authorization distinguishes read-only users, architects, and administrators. State-changing architecture, provenance, workspace, prompt, and administrative operations are protected independently of UI visibility.

Production deployments should:

• use HTTPS through a trusted reverse proxy;
• use a unique administrator credential or Keycloak;
• keep secrets in deployment secret storage rather than source files;
• disable public Swagger access unless explicitly required;
• restrict database, index, backup, and Git-storage access;
• monitor authentication, authorization, and audit events;
• review generated SBOM and vulnerability-assessment evidence.

Report security issues according to SECURITY.md.

Accessibility

The UI is tested across roles, browsers, viewport sizes, zoom levels, forced-colour mode, text spacing, dialogs, and representative loading, empty, offline, error, and conflict states.

See Accessibility for the evidence matrix, manual checks, and known limitations.

Documentation

German documentation is available under docs/de.

Project status

The project is under active development. Compatibility, persistence, security, and migration behavior should be evaluated against the release notes and the exact version deployed. Do not infer production readiness solely from a successful demonstration or an individual quality badge.

Open defects and planned improvements are tracked in GitHub Issues.

Contributing

Contributions should keep the Maven Wrapper as the reproducible entry point and include tests at the lowest appropriate layer. Changes to security, repository routing, persistence, synchronization, import, or export behavior require integration coverage for failure and recovery paths.

Before opening a pull request:

./mvnw verify

Citation

Citation metadata is provided in CITATION.cff. Archived releases can be cited through the DOI badge above.

License

Taxonomy Architecture Analyzer is licensed under the MIT License. Third-party catalogues, models, imported documents, and external services may have their own terms; operators are responsible for verifying that their intended use is permitted.