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.
| 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 | Stores architecture changes in JGit with branches, history, semantic 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 |
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]
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.
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
Legend: ★ = direct match · ⚠ = impact hotspot (≥ 80%) · rounded nodes = anchors/hotspots · percentages = relevance score · arrow labels = relation type
- 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:runOpen 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:runTo browse without loading or downloading the embedding model:
export TAXONOMY_EMBEDDING_ENABLED=false
./mvnw -pl taxonomy-app -am spring-boot:runThe local command starts plain HTTP on port 8080. Do not expose that port directly to the internet.
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 --buildProduction startup rejects missing, placeholder, or short administrator passwords. Review the complete deployment and security documentation before exposing an instance outside a trusted development machine.
Fast default verification:
./mvnw verifyAuthoritative CI-equivalent verification, including integration, browser, quality, coverage, and local ONNX suites:
./mvnw verify -Pci -DrunOnnxTests=trueFocused profiles include:
./mvnw verify -Parchitecture-tests
./mvnw verify -Pdocument-import-tests
./mvnw verify -Parchimate-import-tests
./mvnw verify -Pdatabase-postgres
./mvnw verify -Ponnx
./mvnw verify -Pui-testsThe build generates:
- JUnit and Failsafe reports
- aggregate JaCoCo coverage
- browser and accessibility evidence
- CycloneDX SBOM files
- dependency-alignment and supply-chain policy reports
The Maven reactor separates domain logic, DSL processing, export formats, extension contracts, the Spring application, aggregate coverage, and build policy.
| Module | Responsibility |
|---|---|
taxonomy-domain |
Core architecture and analysis domain types |
taxonomy-dsl |
DSL syntax, parsing, mapping, semantic diff, and model processing |
taxonomy-export |
Export contracts and implementations |
taxonomy-extension-api |
Stable extension interfaces |
taxonomy-app |
Spring Boot application, persistence, security, UI, search, workspaces, and integrations |
taxonomy-coverage |
Reactor-wide coverage aggregation |
taxonomy-build |
Authoritative quality gates and browser verification |
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 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.
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.
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=falseFor deployment provenance and model-policy details, see:
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.
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.
| 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 |
| 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.
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.
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 verifyCitation metadata is provided in CITATION.cff. Archived releases can be cited through the DOI badge above.
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.