Capabilities

Implemented

1. Administer application-wide architecture settings Implemented Governance

   Definition

   Administrators can maintain shared settings such as architecture version, home/export markdown, service tech-stack lists, package lists, stakeholder directory, and GitHub export templates.

   Purpose / Value

   Provides centralized control over repository-wide conventions and presentation settings.

   Scope

   Admin-only settings page and related persistence services.

   Dependencies

   Settings page, settings service, stakeholder persistence, role authorization.

   Measures

   Admin settings page persists global configuration and stakeholder list data.

2. Apply approved proposal changes into current state Implemented Governance

   Definition

   Keystone provides a proposal application workflow that steps through diffs, detects conflicts, accepts resolved state, and writes approved changes into current-state entities.

   Purpose / Value

   Turns architecture proposals into governed changes to the approved repository.

   Scope

   Includes sequential diff review, conflict detection, resolved state submission, and proposal status progression.

   Dependencies

   Proposal apply page, diff service, entity service, proposal repository.

   Measures

   Proposal apply page persists applied changes and updates diff/proposal status.

3. Authenticate users via OpenID Connect providers Implemented Security

   Definition

   Keystone supports OpenID Connect authentication with configurable providers, including Keycloak by default and Azure AD configuration support.

   Purpose / Value

   Integrates architecture access with enterprise identity providers.

   Scope

   Includes sign-in, sign-out, role claim normalization, default role behavior, and profile email initialization.

   Dependencies

   ASP.NET authentication middleware, provider configuration, claims mapping logic, profile service.

   Measures

   Configured OIDC provider support exists in application startup and account flows.

4. Author architecture content in markdown with diagrams and references Implemented Functional

   Definition

   Keystone supports markdown-based authoring with rendered Mermaid diagrams, custom reference resolution, and rich content sections on architecture entities.

   Purpose / Value

   Lets teams capture architecture context in a readable form while retaining structured references.

   Scope

   Applies across entities, proposals, exported HTML, and related detail views.

   Dependencies

   Markdown service, diagram service, reference resolution logic, UI pages, export templates.

   Measures

   Markdown content renders in entity details and export output; Mermaid content is supported in the app and exported pages.

5. Browse architecture through a navigator view Implemented Functional

   Definition

   Keystone provides a Navigator screen for browsing architecture entities by package, domain, entity type, and specific entity selections.

   Purpose / Value

   Improves discoverability of architecture structure and relationships.

   Scope

   Includes domain filter labels, derived service relationship exploration, and JSON detail endpoints backing navigator interactions.

   Dependencies

   Navigator page model, entity service, relationship data, package/domain filters.

   Measures

   Navigator page and filter endpoints are implemented and covered by regression tests.

6. Capture diff-based proposed changes Implemented Governance

   Definition

   Keystone records proposal changes as entity diffs containing base and proposed snapshots, captured metadata, and diff status lifecycle values.

   Purpose / Value

   Provides a maintainable change model that avoids cloning the entire architecture repository for each proposal.

   Scope

   Includes pending, applied, discarded, and conflict diff states.

   Dependencies

   Diff service, proposal entity model, entity service, proposal apply workflow.

   Measures

   Proposal diffs are persisted with base/proposed snapshots and evaluated during apply workflows.

7. Capture domain capabilities within Domain entities Implemented Functional

   Definition

   Domain entities can store ordered capability records with name, status, type, definition, purpose/value, scope, dependencies, and measures.

   Purpose / Value

   Allows domains to represent business and technical capabilities directly inside the architecture knowledge graph.

   Scope

   Includes create, edit, reorder, render, export, proposal overlay, and MCP management of domain capabilities.

   Dependencies

   Domain entity model, capability editor UI, entity detail rendering, export service, MCP domain capability tools.

   Measures

   Capabilities persist on domains and can be queried separately through get_domain_capabilities.

8. Create and manage ADR-style proposals with decision structure Implemented Governance

   Definition

   Keystone supports Proposal entities that function as architecture decision records with context, drivers, options, outcomes, pros/cons, stakeholders, open questions, and use cases.

   Purpose / Value

   Provides a structured way to capture, socialize, and govern architecture change decisions.

   Scope

   Includes create/edit/details/index/apply workflows and stakeholder participation fields.

   Dependencies

   Proposal entity model, proposal pages, stakeholder model, repository support, MCP proposal tools.

   Measures

   Proposal-specific fields and workflows are implemented and persisted.

9. Enforce role-based access control Implemented Security

   Definition

   Keystone enforces role-aware behavior across User, Contributor, and Admin permissions for viewing, editing, governance, and administration workflows.

   Purpose / Value

   Limits sensitive actions to appropriate roles while preserving broad read access.

   Scope

   Includes page authorization, action visibility, edit/create/delete rights, comments, settings, and deleted-items administration.

   Dependencies

   Authentication configuration, role mapping, Razor Page authorization attributes, UI checks, controller authorization.

   Measures

   Role expectations are encoded in the app and validated by regression tests.

10. Export architecture artifacts as PDF, AsyncAPI, and OpenAPI bundles Implemented Functional

    Definition

    Keystone supports additional export formats including PDF output, AsyncAPI export for selected async items, and OpenAPI ZIP export for selected services.

    Purpose / Value

    Allows architecture content to be reused in downstream documentation and interface distribution workflows.

    Scope

    Applies to supported service and message-oriented content.

    Dependencies

    Export service, QuestPDF, service/event metadata, selection workflows.

    Measures

    Export service exposes dedicated methods for PDF, AsyncAPI, and OpenAPI ZIP outputs.

11. Export architecture documentation as static HTML and ZIP Implemented Functional

    Definition

    Keystone can generate a static HTML documentation site and ZIP package for the current architecture repository, including navigation and cross-links.

    Purpose / Value

    Makes architecture documentation portable and easy to publish or share outside the live application.

    Scope

    Includes full-site HTML generation, preview routes, ZIP export, and export filtering options.

    Dependencies

    Export service, markdown service, diagram service, export templates, entity repository.

    Measures

    HTML preview and ZIP export workflows are implemented and documented.

12. Expose Keystone as an MCP server for machine integration Implemented Technical

    Definition

    Keystone exposes a streamable HTTP MCP endpoint with typed tools for searching, reading, creating, updating, and deleting supported entities.

    Purpose / Value

    Enables agentic and automation scenarios against the live architecture repository.

    Scope

    Includes endpoint discovery, tools/list, tools/call, API-key authentication, and entity-specific schemas.

    Dependencies

    MCP controller, entity service, user profile API keys, JSON-RPC handling, tool schema builders.

    Measures

    Production endpoint responds with tool catalog and supports typed domain/entity operations.

13. Expose specialized MCP operations for domain capability maintenance Implemented Technical

    Definition

    Keystone MCP supports targeted operations to read domain capabilities and create or update individual capabilities without replacing unrelated domain properties.

    Purpose / Value

    Makes requirements and capability management safer and easier for automation clients.

    Scope

    Includes get_domain_capabilities, create_domain_capability, and update_domain_capability.

    Dependencies

    MCP controller domain tool definitions, domain capability model, entity persistence.

    Measures

    Specialized domain capability tools are present in the MCP tool catalog.

14. Maintain audit history for entity lifecycle changes Implemented Governance

    Definition

    Keystone records audit information for entity lifecycle actions such as create, update, delete, restore, and related governance events.

    Purpose / Value

    Provides traceability and operational accountability for architecture maintenance.

    Scope

    Applies to persisted entities and is visible in detail experiences and via audit-log entity support.

    Dependencies

    Entity service, audit log model/repository, detail pages, MCP CRUD support for audit-log entities.

    Measures

    Audit log entity support exists and audit information is loaded for entity details.

15. Manage comments and threaded discussion on architecture records Implemented Functional

    Definition

    Keystone supports comments on entities and proposals, including replies, resolution, and deletion behaviors based on user role.

    Purpose / Value

    Enables collaborative review and discussion directly in the architecture repository.

    Scope

    Includes comment retrieval, add, reply, resolve, delete, and dedicated comments page experiences.

    Dependencies

    Comment model, comment service, entity/proposal detail pages, role-based authorization.

    Measures

    Comment service implements add, reply, resolve, and delete operations.

16. Model architecture with typed domain entities Implemented Functional

    Definition

    Keystone supports architecture modeling using first-class typed entities including Domains, Events, Commands, Queries, Services, Designs, Design Categories, ADR-style Proposals, Stakeholders, and Audit Logs.

    Purpose / Value

    Provides a structured, consistent repository for architecture knowledge rather than relying on unstructured documents.

    Scope

    Covers entity type definitions, persistence, CRUD workflows, and cross-type navigation.

    Dependencies

    Base entity model, MongoDB persistence, entity repositories, entity service, Razor Pages UI, MCP CRUD surface.

    Measures

    Entity types are exposed in the application model, UI, services, and MCP tool catalog.

17. Model service interaction patterns Implemented Functional

    Definition

    Keystone models relationships among Services, Events, Commands, and Queries, including producers, consumers, handlers, providers, and dependencies.

    Purpose / Value

    Enables users to document runtime integration patterns and system boundaries in a navigable way.

    Scope

    Includes bidirectional references, service dependencies, parent domain assignment, and detail-page relationship views.

    Dependencies

    Entity models, entity service relationship sync, detail pages, navigator, export rendering.

    Measures

    Relationship fields exist on service/event/command/query entities and are synchronized across linked entities.

18. Operate on MongoDB-backed persistence with service-oriented architecture Implemented Non-Functional

    Definition

    Keystone is implemented as an ASP.NET Core application using MongoDB persistence, dependency-injected repositories/services, and an extensible entity model intended to support additional entity types over time.

    Purpose / Value

    Provides a maintainable technical foundation for evolving architecture knowledge management.

    Scope

    Covers repository abstractions, service-layer business logic, configurable hosting, and deployable web runtime.

    Dependencies

    MongoDB client/database configuration, repositories, services, Razor Pages app composition, Docker/Aspire hosting assets.

    Measures

    The application uses repository/service abstractions, MongoDB persistence, and deployable configuration in code and infrastructure files.

19. Overlay proposed changes onto current-state architecture Implemented Governance

    Definition

    When a proposal is active, Keystone can overlay entity diffs onto current-state entities so users can review a proposed architecture without mutating approved records.

    Purpose / Value

    Separates approved architecture from in-flight change design while keeping comparison simple.

    Scope

    Applies to retrieval, detail rendering, editing in proposal mode, and proposal-aware MCP reads.

    Dependencies

    Proposal context, diff service, entity service, entity details pages, MCP adrId overlays.

    Measures

    Entities can be read with proposal overlays and proposal-mode edits create diffs instead of mutating current state.

20. Personalize user profile, API keys, and integration preferences Implemented Operational

    Definition

    Keystone maintains user profiles with display name, theme, email preferences, API keys, and GitHub export preferences/tokens.

    Purpose / Value

    Supports secure user-specific integrations and a customizable working experience.

    Scope

    Includes profile editing, API key generation/deletion, email notification preferences, and GitHub export settings memory.

    Dependencies

    User profile model, user profile service, profile page, API key authentication in MCP and export automation APIs.

    Measures

    Profiles persist API keys and user settings; MCP authenticates via stored API keys.

21. Preserve soft-deleted entities with restoration and permanent deletion workflows Implemented Operational

    Definition

    Keystone supports soft deletion, deleted-item review, restoration, and permanent deletion for managed entities.

    Purpose / Value

    Improves safety and recoverability when architecture content is removed.

    Scope

    Includes deleted page administration and entity lifecycle state fields.

    Dependencies

    Base entity delete fields, entity service delete/restore/permanent delete methods, deleted page UI.

    Measures

    Delete, restore, and permanent delete workflows are implemented and covered in regression scenarios.

22. Publish static HTML exports to GitHub via UI and automation API Implemented Operational

    Definition

    Keystone can publish generated HTML documentation to GitHub repositories using a user-scoped personal access token, either interactively or via an automation API.

    Purpose / Value

    Supports repeatable publishing of architecture documentation to external repositories.

    Scope

    Includes repository/branch/folder selection, PR creation, deletion of non-existing files, and API-key-authenticated automation endpoint.

    Dependencies

    GitHub export service, export automation controller, user profile PAT storage, export service.

    Measures

    GitHub export UI and automation controller are implemented and call a dedicated GitHub export service.

23. Search architecture entities across the repository Implemented Functional

    Definition

    Keystone supports repository-wide search across supported architecture entity types by name and content.

    Purpose / Value

    Allows users to quickly locate relevant architecture records without knowing their exact location.

    Scope

    Includes search page workflows and MCP search tools for typed entities.

    Dependencies

    Entity service, search page model, MCP search tooling.

    Measures

    Search endpoints and typed MCP search tools are present for core entity categories.

24. Store rich technical metadata for architecture entities Implemented Functional

    Definition

    Keystone stores technical metadata such as tech stack, Docker image, port, compute sizing, OpenAPI specifications, database schema, message schema structure, payload examples, and topic metadata.

    Purpose / Value

    Preserves important implementation context needed for architecture communication and governance.

    Scope

    Primarily applies to Services, Events, Commands, and Queries.

    Dependencies

    Typed entity models, edit forms, markdown/rendering services, navigator JSON endpoints, export service.

    Measures

    Metadata fields are editable, persisted, rendered in UI, and included in API/export workflows.

25. Support AI-assisted architecture authoring and retrieval Implemented Technical

    Definition

    Keystone includes AI-assisted chat and edit workflows that use page context, repository retrieval, conversation history, and targeted field editing guidance.

    Purpose / Value

    Improves author productivity and speeds architecture analysis within the application.

    Scope

    Includes AI chat conversations, contextual retrieval, edit prompt history, and field-targeted edit assistance.

    Dependencies

    AI chat service, AI conversation service, AI retrieval service, AI page context service, AI history service, provider configuration.

    Measures

    Authenticated AI chat API and AI-assisted edit UI hooks are implemented.

26. Support concurrent editing awareness and entity locking Implemented Operational

    Definition

    Keystone uses SignalR-backed edit sessions and lock coordination to show who is editing and to reduce conflicting simultaneous edits.

    Purpose / Value

    Improves operational safety and collaboration during live editing.

    Scope

    Includes join session, request/release lock, force release, user list updates, and live entity data updates.

    Dependencies

    EntityHub SignalR hub, entity lock service, edit page scripts.

    Measures

    SignalR hub methods exist for collaborative edit session membership and lock management.

27. Watch entities and notify interested users of changes Implemented Operational

    Definition

    Users can watch architecture entities, see watched items, receive in-app notifications, and optionally receive email notifications when watched content changes.

    Purpose / Value

    Keeps stakeholders informed when important architecture records are modified.

    Scope

    Includes watch toggling, watched-items page, unread notification count, mark-read, and queued email sending.

    Dependencies

    Watcher IDs on base entities, watch service, notification service, notifications API, SMTP/email queue configuration.

    Measures

    Watch and notification controllers/pages are implemented and notification delivery can be queued.