"""The Target operating model: one explicit graph, checked before anything is derived. parties the organisations with a part in operating the solution teams optional: the teams within a Party, each of one of Team Topologies' four kinds roles positions in a Party, each in a country and at a level, and in a team when there are teams interactions optional: how two teams work together, in one of Team Topologies' three modes; a collaboration says when it ends measures what is measured to show each business outcome the customer stated is being served, at which layer, and by which Capability responsibilities a Role's part in a Capability: accountable, responsible, consulted or informed checks numbered, verifiable conditions on a Capability, a Role or a Responsibility, each traced to what it comes from The Capabilities are the capability model's, by id. A submission is refused while the graph does not hold together, so what the customer approves is complete: every Capability has one Role answerable for it and someone to do it at the hours it is needed, everything the customer said must be kept true is carried by a Check, and every Operational requirement is verified by one. The responsibility matrix, the organisation chart and the staffing and cost are written from the graph by code, as views of it. """ from __future__ import annotations import json from collections.abc import Callable, Collection, Mapping, Sequence from typing import Any from execution_engine.workflows.deliverables import GraphShape, ListShape from app.operating_model import chain, spec, staffing from app.operating_model.catalogue import Catalogue from app.operating_model.names import ( ACCOUNTABLE, COLLABORATION, DEVELOPER_LAYERS, FINDINGS_FILE, GRAPH_FILE, HOURS, INTERACTION_MODES, MEASURE_LAYERS, MEASUREMENT_ENTRY, PARTY_KINDS, RESPONSIBILITY_KINDS, RESPONSIBLE, TARGET_OPERATING_MODEL, TEAM_TYPES, wider, ) from app.operating_model.spec import Upstream from app.operating_model.staffing import RateCard LISTS = ( "parties", "teams", "roles", "responsibilities", "interactions", "measures", "checks", ) OUTCOMES_HEADING = "Business outcomes" MATRIX_HEADING = "Responsibility matrix" STAFFING_HEADING = "Staffing and cost" FINDINGS_HEADING = "Findings" _LETTER = {"accountable": "A", "responsible": "R", "consulted": "C", "informed": "I"} # The graph as the operating-model architect builds it, a few items at a time. SHAPE = GraphShape( attachment=GRAPH_FILE, lists={ "parties": ListShape(("id", "name", "kind"), label="Parties"), "teams": ListShape( ("id", "party", "name", "type"), optional=("purpose",), label="Teams" ), "roles": ListShape( ("id", "party", "name", "country", "level", "hours"), optional=("skills", "team"), label="Roles", ), "interactions": ListShape( ("id", "from", "to", "mode"), optional=("purpose", "until"), label="Interactions", ), "measures": ListShape( ("id", "name", "layer", "outcome", "measured_by"), optional=("framework", "target"), label="Measures", ), "responsibilities": ListShape( ("id", "capability", "role", "kind"), optional=("share",), label="Responsibilities", ), "checks": ListShape( ("id", "on", "condition", "source"), optional=("depends_on_finding",), label="Checks", ), }, ) def parse(text: str) -> tuple[dict[str, list[dict[str, Any]]], list[str]]: """The graph's four lists, and what is wrong with the file's shape.""" try: data = json.loads(text) except ValueError as exc: return {name: [] for name in LISTS}, [f"{GRAPH_FILE}: not valid JSON ({exc})"] if not isinstance(data, dict): return {name: [] for name in LISTS}, [ f"{GRAPH_FILE}: must be an object with {', '.join(LISTS)}" ] graph: dict[str, list[dict[str, Any]]] = {} problems = [] for name in LISTS: entries = data.get(name) or [] if not isinstance(entries, list): problems.append(f"{GRAPH_FILE}: {name} must be a list") entries = [] graph[name] = [dict(item) for item in entries if isinstance(item, dict)] for index, item in enumerate(entries): where = f"{GRAPH_FILE}: {name}[{index}]" if not isinstance(item, dict): problems.append(f"{where} must be an object") continue missing = [ field for field in SHAPE.lists[name].required if not str(item.get(field) or "").strip() ] if missing: problems.append( f"{where} ({item.get('id', 'no id')}) needs {', '.join(missing)}" ) seen = [str(item.get("id")) for item in graph[name] if item.get("id")] problems += [ f"{GRAPH_FILE}: id {identifier} is used more than once in {name}" for identifier in sorted({i for i in seen if seen.count(i) > 1}) ] return graph, problems def read(upstream: Upstream | None) -> dict[str, list[dict[str, Any]]] | None: """The submitted graph from the Deliverables a submission builds on.""" text = ( ((upstream or {}).get(TARGET_OPERATING_MODEL) or {}) .get("attachments", {}) .get(GRAPH_FILE, "") ) return parse(text)[0] if text else None def findings(attachments: Mapping[str, str]) -> list[dict[str, Any]]: text = attachments.get(FINDINGS_FILE, "") return chain.objects(text, FINDINGS_FILE)[0] if text.strip() else [] def check(card: RateCard, frameworks: Collection[str] = ()) -> chain.DataCheck: """What is wrong with a Target operating model, against the capability model, the operating spec and the rate card. `frameworks` are the register's, which a Measure may name.""" def checked(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]: graph, problems = parse(attachments[GRAPH_FILE]) if problems: return problems name = GRAPH_FILE scope = spec.agreed(upstream) capabilities = chain.capabilities(upstream) capability_ids = {str(c["id"]) for c in capabilities} requirement_ids = {str(r["id"]) for r in chain.requirements(upstream)} conditions = spec.ids(spec.conditions(scope)) parties = {str(p["id"]): p for p in graph["parties"]} roles = {str(r["id"]): r for r in graph["roles"]} for party in graph["parties"]: if party.get("kind") not in PARTY_KINDS: problems.append( f"{name}: Party {party['id']}: kind must be one of " f"{', '.join(PARTY_KINDS)}" ) allowed = [ str(c) for c in spec.value(scope, "sourcing.delivery_countries") or [] ] for role in graph["roles"]: where = f"{name}: Role {role['id']}" if role.get("party") not in parties: problems.append( f"{where} is in {role.get('party')}, which is not a Party" ) if role.get("hours") not in HOURS: problems.append(f"{where}: hours must be one of {', '.join(HOURS)}") country = str(role.get("country")) if country not in card.countries: problems.append( f"{where} sits in {country}, which the rate card does not have: " f"{', '.join(sorted(card.countries))}" ) elif allowed and country not in allowed: problems.append( f"{where} sits in {country}; the customer allows only " f"{', '.join(allowed)}" ) if str(role.get("level")) not in card.levels: problems.append( f"{where} is at level {role.get('level')}, which the rate card " f"does not have: {', '.join(card.levels)}" ) problems += check_teams(graph, parties, name) by_capability: dict[str, list[dict[str, Any]]] = {} for item in graph["responsibilities"]: where = f"{name}: Responsibility {item['id']}" if item.get("kind") not in RESPONSIBILITY_KINDS: problems.append( f"{where}: kind must be one of {', '.join(RESPONSIBILITY_KINDS)}" ) if item.get("role") not in roles: problems.append( f"{where} names {item.get('role')}, which is not a Role" ) if upstream is not None and item.get("capability") not in capability_ids: problems.append( f"{where} names {item.get('capability')}, which is not a " "Capability of the capability model" ) by_capability.setdefault(str(item.get("capability")), []).append(item) for capability in capabilities: identifier = str(capability["id"]) held = by_capability.get(identifier, []) accountable = [r for r in held if r.get("kind") == ACCOUNTABLE] responsible = [r for r in held if r.get("kind") == RESPONSIBLE] if len(accountable) != 1: problems.append( f"{name}: Capability {identifier} has {len(accountable)} " "accountable Roles; it needs exactly one" ) if not responsible: problems.append( f"{name}: Capability {identifier} has no responsible Role" ) continue needed = str(capability.get("hours")) worked = [ str(roles[str(r["role"])].get("hours")) for r in responsible if r.get("role") in roles ] if ( needed in HOURS and worked and all(hours in HOURS and wider(needed, hours) for hours in worked) ): problems.append( f"{name}: Capability {identifier} is needed {needed}, and no " "Role responsible for it works those hours" ) problems += [ f"{name}: {fault}" for fault in staffing.shares(graph["responsibilities"])[1] ] found = findings(attachments) finding_ids = {str(item["id"]) for item in found} on = ( capability_ids | set(roles) | {str(r["id"]) for r in graph["responsibilities"]} | {str(team["id"]) for team in graph["teams"]} | {str(i["id"]) for i in graph["interactions"]} | {str(m["id"]) for m in graph["measures"]} ) carried: set[str] = set() for item in graph["checks"]: where = f"{name}: Check {item['id']}" source = str(item.get("source")) carried.add(source) if upstream is not None and item.get("on") not in on: problems.append( f"{where} is on {item.get('on')}, which is not a Capability, a " "Role or a Responsibility" ) if upstream is not None and source not in requirement_ids | set(conditions): problems.append( f"{where}: source {source} is not an Operational requirement " "or a Condition" ) depends = item.get("depends_on_finding") if depends and depends not in finding_ids: problems.append(f"{where} depends on {depends}, which is not a finding") problems += [ f"{name}: Condition {identifier} is carried by no Check" for identifier in conditions if identifier not in carried ] # Every Operational requirement is verified: by a Check from it, or from a # Condition it comes from. Serving it with a Capability says who does the # work; a Check says how anyone would know it is done. for requirement in chain.requirements(upstream): identifier = str(requirement["id"]) named = requirement.get("source") or [] named = [named] if isinstance(named, str) else named if identifier not in carried and not any( str(source) in carried and str(source) in conditions for source in named ): problems.append( f"{name}: Operational requirement {identifier} is verified by no " "Check: give it one, from the requirement or from a Condition " "it comes from" ) problems += check_measures( graph, scope, capabilities, by_capability, roles, frameworks, name ) problems += check_findings( attachments, scope, on | {str(c["id"]) for c in graph["checks"]} | requirement_ids, ) return problems return checked def check_teams( graph: Mapping[str, Sequence[Mapping[str, Any]]], parties: Mapping[str, Any], name: str, ) -> list[str]: """What is wrong with the teams and how they work together. Teams are optional. When there are any, each is of one of Team Topologies' four kinds, a Role in a team belongs to that team's Party, and two teams work together in one of its three modes. A collaboration is a stage, not a standing arrangement: it says when it ends. """ problems = [] teams = {str(team["id"]): team for team in graph["teams"]} for team in graph["teams"]: where = f"{name}: Team {team['id']}" if team.get("type") not in TEAM_TYPES: problems.append(f"{where}: type must be one of {', '.join(TEAM_TYPES)}") if team.get("party") not in parties: problems.append(f"{where} is in {team.get('party')}, which is not a Party") for role in graph["roles"]: team_id = role.get("team") if not team_id: continue found = teams.get(str(team_id)) if found is None: problems.append( f"{name}: Role {role['id']} is in {team_id}, which is not a Team" ) elif found.get("party") != role.get("party"): problems.append( f"{name}: Role {role['id']} is in {role.get('party')}, and its team " f"{team_id} is in {found.get('party')}" ) for item in graph["interactions"]: where = f"{name}: Interaction {item['id']}" if item.get("mode") not in INTERACTION_MODES: problems.append( f"{where}: mode must be one of {', '.join(INTERACTION_MODES)}" ) for end in ("from", "to"): if item.get(end) not in teams: problems.append(f"{where}: {end} {item.get(end)} is not a Team") if item.get("from") == item.get("to"): problems.append(f"{where} is between a team and itself") if ( item.get("mode") == COLLABORATION and not str(item.get("until") or "").strip() ): problems.append( f"{where} is a collaboration and does not say when it ends: give " "`until`, and what the teams work in after" ) return problems def check_measures( graph: Mapping[str, Sequence[Mapping[str, Any]]], scope: Mapping[str, Any], capabilities: Sequence[Mapping[str, Any]], by_capability: Mapping[str, Sequence[Mapping[str, Any]]], roles: Mapping[str, Any], frameworks: Collection[str], name: str, ) -> list[str]: """Every business outcome the customer stated is shown by something measured, and everything measured shows one: nothing is measured for its own sake. A Measure is taken by a Capability someone is responsible for. Where the model measures how work flows, it measures all three layers: delivery outcomes, sustainable productivity and friction. No one of them stands in for the others. """ problems = [] outcomes = {str(o["id"]): o for o in spec.business_outcomes(scope)} capability_ids = {str(c["id"]) for c in capabilities} measured: set[str] = set() for item in graph["measures"]: where = f"{name}: Measure {item['id']}" if item.get("layer") not in MEASURE_LAYERS: problems.append( f"{where}: layer must be one of {', '.join(MEASURE_LAYERS)}" ) outcome = str(item.get("outcome")) measured.add(outcome) if outcome not in outcomes: problems.append( f"{where} shows {outcome}, which is not a business outcome the " "customer stated" + (f": {', '.join(outcomes)}" if outcomes else "; none were stated") ) taker = str(item.get("measured_by")) if taker not in capability_ids: problems.append( f"{where} is measured by {taker}, which is not a Capability" ) elif not any( r.get("kind") == "responsible" and r.get("role") in roles for r in by_capability.get(taker, ()) ): problems.append( f"{where} is measured by {taker}, and nobody is responsible for it" ) if item.get("framework") and frameworks and item["framework"] not in frameworks: problems.append( f"{where} names framework {item['framework']}, which is not in the register" ) problems += [ f"{name}: business outcome {identifier} ({outcomes[identifier].get('outcome')}) " "is shown by no Measure" for identifier in outcomes if identifier not in measured ] measurers = { str(c["id"]) for c in capabilities if c.get("catalogue") == MEASUREMENT_ENTRY } # Only once there is an outcome to tie Measures to: with none, no Measure can # be accepted, and asking for three of them could never be met. if measurers and outcomes: layers = { str(m.get("layer")) for m in graph["measures"] if m.get("measured_by") in measurers } missing = [layer for layer in DEVELOPER_LAYERS if layer not in layers] if missing: problems.append( f"{name}: {', '.join(sorted(measurers))} measures how work flows and has " f"no Measure at the {', '.join(missing)} layer; each layer answers a " "different question and none stands in for another" ) return problems def render_outcomes( graph: Mapping[str, Sequence[Mapping[str, Any]]], scope: Mapping[str, Any], names: Mapping[str, str], ) -> str: """Each business outcome, with what shows it is served and who answers for it.""" outcomes = spec.business_outcomes(scope) if not outcomes: return ( "The customer stated no business outcomes, so nothing in this operating " "model is tied to one. Ask what the business wants from the solution, " "and how it would know." ) roles = {str(r["id"]): r for r in graph["roles"]} answerable: dict[str, str] = {} for item in graph["responsibilities"]: if item.get("kind") == "accountable" and item.get("role") in roles: answerable[str(item.get("capability"))] = str( roles[str(item["role"])].get("name") ) lines = [] for outcome in outcomes: target = f" Target: {outcome['target']}." if outcome.get("target") else "" lines += [f"**{outcome['id']}: {outcome.get('outcome')}**{target}", ""] shown = [m for m in graph["measures"] if m.get("outcome") == outcome["id"]] if not shown: lines += ["Nothing measured shows this outcome.", ""] continue lines += [ "| Measure | Layer | Framework | Target | Measured by | Answerable |", "| --- | --- | --- | --- | --- | --- |", ] lines += [ f"| {m.get('name')} | {str(m.get('layer', '')).replace('_', ' ')} | " f"{m.get('framework') or ''} | {m.get('target') or ''} | " f"{names.get(str(m.get('measured_by')), m.get('measured_by'))} | " f"{answerable.get(str(m.get('measured_by')), '')} |" for m in shown ] lines.append("") return "\n".join(lines).rstrip() def check_findings( attachments: Mapping[str, str], scope: Mapping[str, Any], known: set[str] ) -> list[str]: """What is wrong with findings.json. It may be an empty list.""" text = attachments.get(FINDINGS_FILE, "") if not text.strip(): return [] entries, problems = chain.objects(text, FINDINGS_FILE) item_ids = set(spec.ids(spec.items(scope))) for entry in entries: where = f"{FINDINGS_FILE}: {entry['id']}" for field in ("lacks", "proposed"): if not str(entry.get(field) or "").strip(): problems.append(f"{where} needs {field}") about = [str(i) for i in entry.get("about") or []] needed_by = [str(i) for i in entry.get("needed_by") or []] if not about: # A finding is about the solution: it names what in it is lacking. problems.append( f"{where} names no Item of the solution under about. What the " "operating model can provide itself, such as staffing, hours, a Role, " "a process or a tool, is not a finding: design it" ) if not needed_by: problems.append(f"{where} must say what needs it, under needed_by") problems += [ f"{where} is about {identifier}, which is not an Item of the operating spec" for identifier in about if scope and identifier not in item_ids ] problems += [ f"{where} is needed by {identifier}, which is not in the operating model" for identifier in needed_by if identifier not in known ] return problems # --- the views code writes ----------------------------------------------------------- def render_matrix( graph: Mapping[str, Sequence[Mapping[str, Any]]], names: Mapping[str, str] ) -> str: """Who is accountable, responsible, consulted and informed for each Capability.""" roles = list(graph["roles"]) # A Role may hold more than one part in a Capability: answerable for it and # doing it. Both are shown. held: dict[tuple[str, str], str] = {} for item in graph["responsibilities"]: key = (str(item.get("capability")), str(item.get("role"))) letter = _LETTER.get(str(item.get("kind")), "?") held[key] = f"{held[key]}/{letter}" if key in held else letter header = "| Capability | " + " | ".join(str(r.get("name")) for r in roles) + " |" rule = "| --- | " + " | ".join("---" for _ in roles) + " |" rows = [ f"| {name} ({identifier}) | " + " | ".join(held.get((identifier, str(r["id"])), "") for r in roles) + " |" for identifier, name in names.items() ] legend = "A accountable, R responsible, C consulted, I informed." return "\n".join([f"## {MATRIX_HEADING}", "", header, rule, *rows, "", legend, ""]) def _node(identifier: Any) -> str: return str(identifier).replace("-", "_") def _role_node(role: Mapping[str, Any], indent: str) -> str: return ( f'{indent}{_node(role["id"])}["{role.get("name")}
{role.get("country")}, ' f'{role.get("level")}, {role.get("hours")}"]' ) def render_organisation(graph: Mapping[str, Sequence[Mapping[str, Any]]]) -> str: """The Parties, their teams and the Roles in each, and how the teams work together, as a Mermaid chart.""" teams = graph.get("teams") or [] lines = ["flowchart TB"] for party in graph["parties"]: lines.append( f' subgraph {_node(party["id"])}["{party.get("name")} ({party.get("kind")})"]' ) for team in teams: if team.get("party") != party["id"]: continue kind = str(team.get("type", "")).replace("_", "-") lines.append( f' subgraph {_node(team["id"])}["{team.get("name")} ({kind} team)"]' ) lines += [ _role_node(role, " ") for role in graph["roles"] if role.get("team") == team["id"] ] lines.append(" end") lines += [ _role_node(role, " ") for role in graph["roles"] if role.get("party") == party["id"] and not role.get("team") ] lines.append(" end") for item in graph.get("interactions") or []: mode = str(item.get("mode", "")).replace("_", "-") label = mode + (f" until {item['until']}" if item.get("until") else "") lines.append(f' {_node(item["from"])} -- "{label}" --> {_node(item["to"])}') return "\n".join(lines) + "\n" def _money(amount: Any, currency: str) -> str: return "not priced" if amount is None else f"{amount:,} {currency}" def render_staffing(result: Mapping[str, Any], budget: Any = None) -> str: """People and cost per Role and in total, with the prices they were worked from.""" currency = str(result["currency"]) card = result["rate_card"] conversion = result["conversion"] lines = [ f"## {STAFFING_HEADING}", "", "| Role | Party | Country | Level | Hours | Effort a month | People | Cost a month |", "| --- | --- | --- | --- | --- | --- | --- | --- |", ] lines += [ f"| {row['name']} | {row.get('party_name', row['party'])} | " f"{row['country']} | {row['level']} | " f"{row['hours']} | {row['effort_hours_per_month']} h | {row['people']} | " f"{_money(row['cost_per_month'], currency)} |" for row in result["roles"] ] lines += [ "", ( f"{result['people']} people in all. Cost a month: " f"{_money(result['cost_per_month'], currency)}." ), ] if isinstance(budget, (int, float)) and not isinstance(budget, bool): over = result["cost_per_month"] - budget lines.append( f"The monthly budget is {_money(round(budget), currency)}: " + ( f"this is over it by {_money(round(over), currency)}." if over > 0 else "this is within it." ) ) lines += [ "", f"Worked from rate card `{card['name']}`, version `{card['version']}`" + ( ". **Its figures are placeholders: no price has been set, and this cost " "is an illustration.**" if card["draft"] else "." ), ] if conversion["from"] != currency: lines.append( f"Converted from {conversion['from']} at {conversion['rate']}, a rate " f"set on {conversion['as_of']}." ) lines += [ ( "The customer's own staff are counted and not priced. A Role that covers " "hours wider than a working day is never smaller than the team that can " "cover them." ), "", ] return "\n".join(lines) def render_findings(found: Sequence[Mapping[str, Any]]) -> str: if not found: return "" lines = [ f"## {FINDINGS_HEADING}", "", ( "What operating this solution needs that the solution, as described, does " "not provide. Nothing here was designed around: each is for whoever owns " "the design." ), "", ] lines += [ f"- **{item['id']}** ({', '.join(str(i) for i in item.get('about') or []) or 'the solution'}): " f"{item.get('lacks')} Proposed: {item.get('proposed')}" for item in found ] return "\n".join(lines) + "\n" Views = Callable[[str, dict[str, str], Upstream | None], tuple[str, dict[str, str]]] def views(catalogue: Catalogue, card: RateCard) -> Views: """Add the matrix, the staffing and the findings to an accepted submission.""" from app.operating_model.names import ORGANISATION_FILE, STAFFING_FILE def add( content: str, attachments: dict[str, str], upstream: Upstream | None ) -> tuple[str, dict[str, str]]: graph, _ = parse(attachments[GRAPH_FILE]) scope = spec.agreed(upstream) capabilities = chain.capabilities(upstream) currency = str(spec.value(scope, "commercial.currency") or card.currency) result = staffing.compute(graph, capabilities, card, currency) found = findings(attachments) # A Revision replaces these sections, never stacks a second copy. content = content.split(f"\n## {MATRIX_HEADING}")[0].rstrip() parts = [ content, render_matrix(graph, chain.names_of(capabilities, catalogue)), render_staffing(result, spec.value(scope, "commercial.monthly_run_budget")), render_findings(found), ] attachments[ORGANISATION_FILE] = render_organisation(graph) attachments[STAFFING_FILE] = json.dumps(result, indent=2, ensure_ascii=False) attachments.setdefault(FINDINGS_FILE, "[]") return "\n\n".join(part.rstrip() for part in parts if part) + "\n", attachments return add