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.

What the application provides

Capability	Description
Rapid architecture prototyping	Derives candidate cross-layer architecture elements, relations, and views from requirements and source documents
Hierarchical analysis trace	Scores catalogue roots, intermediate nodes, and leaves while preserving the paths and rationales behind the result
Architecture views	Builds cross-layer views from selected elements and typed relations
Traceable source import	Extracts bounded candidates from PDF and DOCX sources and links accepted requirements to source versions and fragments
Versioned architecture DSL	Keeps explicit DSL checkpoints in JGit and durable semantic editor revisions in a separate operation journal; supports branches, diffs, merges, reverts, and selective transfer
Search	Provides full-text search and optional local ONNX vector search through Hibernate Search and Lucene
Multi-user workspaces	Separates personal workspaces from the shared architecture repository
Export	Produces machine-readable and presentation-oriented architecture outputs
Pluggable AI	Supports cloud providers and a local ONNX option; deterministic browsing remains available without an LLM

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 review and refinement]
    E --> F[Versioned architecture change]
    F --> G[Diagram, report, or data export]

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.

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

Production startup rejects missing, placeholder, or short administrator passwords. 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

Authoritative CI-equivalent verification, including integration, browser, quality, coverage, and local ONNX suites:

./mvnw verify -Pci -DrunOnnxTests=true

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

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. Its report is written to taxonomy-build/target/architecture-module-graph.txt. 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

Architecture

Taxonomy is a modular monolith with one deployable Spring Boot application. The Maven reactor contains fifteen child modules: four framework-free foundations, seven 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

Module	Responsibility
taxonomy-domain	Framework-free shared architecture and analysis types
taxonomy-dsl	Framework-free DSL syntax, parsing, mapping, semantic diff, and model processing
taxonomy-export	Framework-free export contracts, codecs, and neutral rendering
taxonomy-extension-api	Framework-free extension interfaces and metadata
taxonomy-workspace	Repository/workspace identity, versioning, editor operation journal, undo/redo, Git checkpoints, and JGit storage
taxonomy-knowledge	Catalogue and seeds, relations and hypotheses, search, indexes, and local embeddings
taxonomy-templates	Versioned document templates, OOXML validation, materialization, WebDAV, and template administration
taxonomy-interop	External-tool connectors, reviewed exchange, identity mappings, and synchronization checkpoints
taxonomy-architecture	Architecture derivation, scoring, gaps, patterns, recommendations, diagrams, and reports
taxonomy-analysis	Requirement/LLM analysis, provider gateways, prompts and policies, parsing, and analysis sessions
taxonomy-portfolio	Projects, versioned requirements, analysis jobs/results, reviews, recovery, and workbench snapshots
taxonomy-app	The only executable application: Spring wiring, cross-context HTTP/UI composition, security/observability, deployment configuration, and database migrations
taxonomy-tooling	Build and release tooling; not a runtime feature library
taxonomy-coverage	Reactor-wide coverage aggregation
taxonomy-build	Authoritative quality gates, whole-reactor checks, and browser verification

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

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_MODEL_DIR=/absolute/path/to/bge-small-en-v1.5
export TAXONOMY_EMBEDDING_ALLOW_DOWNLOAD=false

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

Document	Purpose
User guide	Main workflows and UI concepts
API reference	REST endpoints and integration details
Architecture	Components, boundaries, and runtime design
Configuration reference	Environment variables and profiles
Database setup	Supported database configurations
Repository topology	Shared repository and workspace routing
Git integration	Versioning and external repository behavior
Sparx EA exchange / Deutsch	Experimental reviewed XMI subset, mapping and explicit compatibility limits
Security	Authentication, authorization, and deployment controls
AI transparency	AI usage, limitations, and operator responsibilities
Accessibility	Accessibility scope and verification

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.