Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ specification; development agents read exactly the version that was approved, th
allowed to use the app from the identity provider's directory (Keycloak or Microsoft Entra ID).
- **Roles across projects:** select an existing role or create one, then describe what it does in this
project.
- **Non-functional requirements baseline:** global NFRs (`BL-01`, …) by category such as performance, availability,
security or usability. Every project shows them as read-only items next to its own NFRs, and the PRD export
includes them. They are not part of project versions, so changing the baseline never changes a project's state.
Only users with the application role `ARCHITECT` maintain it (see [Identity provider](#identity-provider)).
- **Whole-project review:** reviewers accept, request changes or reject a frozen candidate, and can suggest
wording on any element. Authors apply or dismiss suggestions afterwards.
- **Immutable versions:** approval turns the candidate into `v1`, `v2`, … A database trigger keeps approved
Expand All @@ -81,9 +85,13 @@ specification; development agents read exactly the version that was approved, th
|---|---|
| ![Review](docs/images/review.png) | ![Compare](docs/images/compare.png) |

| Requirement with diagram, traceability and external links |
| Requirement with diagram, traceability and external links | Projects and what needs your attention |
|---|---|
| ![Requirement](docs/images/element.png) | ![Projects](docs/images/home.png) |

| Non-functional requirements baseline, inherited by every project |
|---|
| ![Requirement](docs/images/element.png) |
| ![Baseline](docs/images/baseline.png) |

## Architecture

Expand Down Expand Up @@ -133,6 +141,7 @@ Open <http://localhost:8080> and sign in as `owner1` / `password`.
| `owner2`, `contrib1` | second owner, contributor |
| `reviewer1`, `reviewer2` | reviewers |
| `viewer1` | read-only user |
| `architect1` | architect: maintains the NFR baseline |

All passwords are `password`. Local services:

Expand Down Expand Up @@ -225,13 +234,14 @@ agents that assess requirements, suggest improvements or build a backlog with th
| Tool | Returns |
|---|---|
| `list_projects` | projects, owners, state, tags, domains |
| `get_prd` | the whole specification as one Markdown PRD |
| `search_requirements` | elements by type, tag or text |
| `get_requirement` | one element with traceability and external links |
| `get_prd` | the whole specification as one Markdown PRD, including the NFR baseline |
| `search_requirements` | elements by type, tag or text, plus matching baseline NFRs (project `baseline`) |
| `get_requirement` | one element with traceability and external links; `BL-` keys work with any project |
| `get_traceability` | BR → SR → FR/NFR → scenario graph, with its gaps |
| `list_versions`, `diff_versions` | version history and unified diffs |
| `get_review_status` | reviewers, decisions, open suggestions |
| `get_external_links`, `list_roles` | JIRA / ADO references, shared roles |
| `list_baseline_requirements` | the NFR baseline, optionally by category or text |

- **Approved by default:** tools return the latest approved version unless `version` is `"2"`, `"3-rc1"` or
`"draft"`, so agents never build on unreviewed work by accident.
Expand Down Expand Up @@ -406,6 +416,8 @@ still be overridden with the variable.
| `REQLITH_IDP_AUTHORIZATION_URI`, `_TOKEN_URI`, `_JWKS_URI`, `_USER_INFO_URI`, `_END_SESSION_URI` | `GENERIC` only (first three) | derived from the type | endpoint overrides |
| `REQLITH_IDP_MCP_AUDIENCE` | no | not checked | required `aud` of IDP access tokens at `/mcp` (Entra: the API's application ID URI) |
| `REQLITH_IDP_DIRECTORY` | no | `KEYCLOAK` (`NONE` otherwise) | invitation suggestions: `NONE`, `KEYCLOAK`, `ENTRA` or `ENTRA_ASSIGNED` |
| `REQLITH_IDP_ROLES_CLAIM` | no | `roles` | token claim with the user's IDP roles; dotted names reach nested claims (`realm_access.roles`) |
| `REQLITH_IDP_ARCHITECT_ROLES` | no | `ARCHITECT` | IDP roles (comma-separated, case-insensitive) that grant the application role `ARCHITECT` |
| `MANAGEMENT_PORT` | no | `8081` | actuator port |
| `LOGGING_LEVEL_IO_REQLITH` | no | `DEBUG` (`INFO` otherwise) | application log level |

Expand All @@ -427,6 +439,10 @@ from the issuer. Every endpoint can be overridden with `REQLITH_IDP_*_URI`.
User e-mail addresses (used to match invitations) come from the `email` claim. When that claim is missing, as it
often is with Entra, they come from `preferred_username` or `upn` if those are addresses.

**Application roles** come from the claim `REQLITH_IDP_ROLES_CLAIM` (default `roles`) at sign-in. A user holding
one of `REQLITH_IDP_ARCHITECT_ROLES` becomes an `ARCHITECT` and may maintain the NFR baseline. Project roles
(owner, contributor, reviewer) are managed in Reqlith itself. A changed role takes effect at the next sign-in.

**Invitation suggestions** always include users who have signed in before. With a directory, everyone allowed to use
the app can be suggested, which also shows those names and addresses to every signed-in user.

Expand All @@ -440,6 +456,10 @@ the app can be suggested, which also shows those names and addresses to every si
admin API (26.4+) requires it, and Reqlith requests it only for directory calls. Suggestions list the realm's
enabled users.
- **MCP over OAuth:** a public client for MCP clients (the local realm has `reqlith-mcp`).
- **Architects:** create the realm role `ARCHITECT` and assign it. Add a *User Realm Role* mapper to the client
with token claim name `roles`, multivalued, added to the ID token (the local realm does this, and `architect1`
has the role). To use Keycloak's built-in `realm_access.roles` instead, switch on *Add to ID token* for the
*realm roles* mapper of the `roles` client scope and set `REQLITH_IDP_ROLES_CLAIM=realm_access.roles`.

</details>

Expand All @@ -461,6 +481,9 @@ the app can be suggested, which also shows those names and addresses to every si
`api://reqlith`) and a scope. In the manifest, set `requestedAccessTokenVersion` (or `accessTokenAcceptedVersion`)
to `2` so access tokens carry the v2 issuer. Set `REQLITH_IDP_MCP_AUDIENCE` to the audience of those tokens
(usually the application ID URI or client id). Personal access tokens work regardless.
6. **Architects (optional):** under *App roles*, create a role with value `ARCHITECT` for users/groups and assign
it in the enterprise application. Entra puts assigned app roles in the ID token's `roles` claim. If your role
has another value, set `REQLITH_IDP_ARCHITECT_ROLES` to it.

```bash
REQLITH_IDP_TYPE=ENTRA
Expand Down
Binary file added docs/images/baseline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/compare.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/element.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/home.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/review.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
45 changes: 45 additions & 0 deletions src/main/dev/keycloak/reqlith-realm.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@
"sslRequired": "none",
"registrationAllowed": false,
"loginWithEmailAllowed": true,
"roles": {
"realm": [
{
"name": "ARCHITECT",
"description": "Maintains the Reqlith non-functional requirements baseline"
}
]
},
"clients": [
{
"clientId": "reqlith-app",
Expand Down Expand Up @@ -36,6 +44,23 @@
],
"optionalClientScopes": [
"kc-admin-api"
],
"protocolMappers": [
{
"name": "realm roles",
"protocol": "openid-connect",
"protocolMapper": "oidc-usermodel-realm-role-mapper",
"consentRequired": false,
"config": {
"multivalued": "true",
"claim.name": "roles",
"jsonType.label": "String",
"id.token.claim": "true",
"access.token.claim": "true",
"userinfo.token.claim": "true",
"introspection.token.claim": "true"
}
}
]
},
{
Expand Down Expand Up @@ -180,6 +205,26 @@
"default-roles-reqlith"
]
},
{
"id": "8e3b6f0a-2c4d-4b7e-9a51-6d2f0c9e7b13",
"username": "architect1",
"email": "architect1@reqlith.local",
"firstName": "Ada",
"lastName": "Archer",
"enabled": true,
"emailVerified": true,
"credentials": [
{
"type": "password",
"value": "password",
"temporary": false
}
],
"realmRoles": [
"default-roles-reqlith",
"ARCHITECT"
]
},
{
"username": "service-account-reqlith-app",
"enabled": true,
Expand Down
2 changes: 1 addition & 1 deletion src/main/dev/scripts/podman-dev.sh
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ up() {
fi

echo "MSSQL localhost:1433 (db reqlith, user reqlith_app)"
echo "Keycloak http://localhost:8180 (admin/admin, realm reqlith, users owner1..viewer1 / password)"
echo "Keycloak http://localhost:8180 (admin/admin, realm reqlith, users owner1..viewer1, architect1 / password)"
echo "Renderer http://localhost:3000 (Gotenberg, PDF export)"
$with_app && echo "App http://localhost:8080 (actuator on http://localhost:8081/actuator)"
return 0
Expand Down
4 changes: 4 additions & 0 deletions src/main/kotlin/io/reqlith/config/ReqlithProperties.kt
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ data class ReqlithProperties(
val directory: DirectoryType = DirectoryType.NONE,
/** Required `aud` of IDP access tokens sent to /mcp (Entra: the API's application ID URI); blank = not checked. */
val mcpAudience: String? = null,
/** Claim with the user's IDP roles (Keycloak realm roles mapped to `roles`; Entra app roles). Dotted names reach nested claims. */
val rolesClaim: String = "roles",
/** IDP roles that make a user an architect, who maintains the non-functional requirements baseline. */
val architectRoles: List<String> = listOf("ARCHITECT"),
)

enum class IdpType {
Expand Down
76 changes: 76 additions & 0 deletions src/main/kotlin/io/reqlith/controller/BaselineController.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
package io.reqlith.controller

import io.reqlith.exception.ValidationException
import io.reqlith.model.dto.CurrentUser
import io.reqlith.model.entity.BaselineCategory
import io.reqlith.service.BaselineService
import io.reqlith.service.MarkdownRenderer
import org.springframework.security.core.annotation.AuthenticationPrincipal
import org.springframework.stereotype.Controller
import org.springframework.ui.Model
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestParam

/** The non-functional requirements baseline: everyone reads it, architects maintain it. */
@Controller
class BaselineController(private val baseline: BaselineService, private val markdown: MarkdownRenderer) {

@GetMapping("/baseline")
fun list(@AuthenticationPrincipal user: CurrentUser, model: Model): String {
model.addAttribute("baseline", baseline.all().groupBy { it.category })
model.addAttribute("categories", BaselineCategory.entries)
model.addAttribute("canEdit", baseline.canEdit(user))
return "baseline/list"
}

@PostMapping("/baseline")
fun create(
@AuthenticationPrincipal user: CurrentUser,
@RequestParam category: BaselineCategory,
@RequestParam title: String,
@RequestParam(required = false) body: String?,
model: Model,
): String = try {
"redirect:/baseline/${baseline.create(user, category, title, body).key}"
} catch (e: ValidationException) {
model.addAttribute("error", e)
model.addAttribute("newCategory", category)
model.addAttribute("newTitle", title)
model.addAttribute("newBody", body)
list(user, model)
}

@GetMapping("/baseline/{key}")
fun show(@AuthenticationPrincipal user: CurrentUser, @PathVariable key: String, model: Model): String {
val requirement = baseline.get(key)
model.addAttribute("requirement", requirement)
model.addAttribute("bodyHtml", markdown.render(requirement.bodyMd))
model.addAttribute("categories", BaselineCategory.entries)
model.addAttribute("canEdit", baseline.canEdit(user))
return "baseline/show"
}

@PostMapping("/baseline/{key}")
fun update(
@AuthenticationPrincipal user: CurrentUser,
@PathVariable key: String,
@RequestParam category: BaselineCategory,
@RequestParam title: String,
@RequestParam(required = false) body: String?,
model: Model,
): String = try {
baseline.update(user, baseline.get(key), category, title, body)
"redirect:/baseline/$key"
} catch (e: ValidationException) {
model.addAttribute("error", e)
show(user, key, model)
}

@PostMapping("/baseline/{key}/delete")
fun delete(@AuthenticationPrincipal user: CurrentUser, @PathVariable key: String): String {
baseline.delete(user, baseline.get(key))
return "redirect:/baseline"
}
}
1 change: 1 addition & 0 deletions src/main/kotlin/io/reqlith/controller/ProjectController.kt
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ class ProjectController(
model.addAttribute("document", document)
model.addAttribute("changes", changesSinceApproval(project, document))
model.addAttribute("html", RenderedDocument.of(document) { support.render(it, project, document) })
model.addAttribute("baselineHtml", support.renderBaseline())
model.addAttribute("types", ElementType.entries)
model.addAttribute("incoming", document.incomingLinks())
return "project/document"
Expand Down
12 changes: 10 additions & 2 deletions src/main/kotlin/io/reqlith/controller/ProjectViewSupport.kt
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import io.reqlith.model.entity.ElementType
import io.reqlith.model.entity.MemberRole
import io.reqlith.model.entity.Project
import io.reqlith.model.entity.ProjectStatus
import io.reqlith.service.BaselineService
import io.reqlith.service.MarkdownRenderer
import io.reqlith.service.MembershipService
import io.reqlith.service.ProjectAccess
Expand All @@ -30,6 +31,7 @@ class ProjectViewSupport(
private val versions: VersionService,
private val reviews: ReviewService,
private val codec: SnapshotCodec,
private val baseline: BaselineService,
) {
fun populate(model: Model, project: Project, user: CurrentUser, document: ProjectDocument, active: String) {
val role = access.roleOf(project, user)
Expand All @@ -44,7 +46,9 @@ class ProjectViewSupport(
model.addAttribute("locked", project.status == ProjectStatus.IN_REVIEW)
model.addAttribute("owners", owners)
model.addAttribute("active", active)
model.addAttribute("sections", sections(project, document))
val baselineItems = baseline.all()
model.addAttribute("baseline", baselineItems)
model.addAttribute("sections", sections(project, document, baselineItems.size))
val state = state(project, document)
model.addAttribute("stateLabel", state.first)
model.addAttribute("stateClass", state.second)
Expand Down Expand Up @@ -84,7 +88,10 @@ class ProjectViewSupport(
?: document.role(key)?.let { Reference("/roles/$key", "$key · ${it.name}") }
}

private fun sections(project: Project, document: ProjectDocument): List<NavSection> {
/** Baseline descriptions rendered for the document views (key to HTML). */
fun renderBaseline(): Map<String, String> = baseline.all().associate { it.key to markdown.render(it.bodyMd) }

private fun sections(project: Project, document: ProjectDocument, baselineCount: Int): List<NavSection> {
val base = "/p/${project.key}"
val basic = listOf(
NavSection("Problem statement", null, "$base/draft/document#problem-statement", "problem"),
Expand All @@ -94,6 +101,7 @@ class ProjectViewSupport(
fun typed(type: ElementType) = NavSection(type.section, document.elementsOf(type).size, "$base/draft?type=${type.name}", type.name)
return basic + listOf(
typed(ElementType.BR), typed(ElementType.SR), typed(ElementType.FR), typed(ElementType.NFR),
NavSection("Baseline NFRs", baselineCount, "$base/draft/document#baseline", "baseline"),
typed(ElementType.AS), typed(ElementType.RK),
NavSection("Roles", document.roles.size, "$base/roles", "roles"),
typed(ElementType.SC), typed(ElementType.DP),
Expand Down
Loading