askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
flow.py · 9.1 KB · 195 lines
| 1 | """site_flow -- the workflow, viewable: /flow and /flow/{collection}. |
| 2 | |
| 3 | Dan's observation, which most web software never answered: apps forgot |
| 4 | help, and frameworks forgot docs. The reason was structural -- their |
| 5 | workflow existed only as the union of whatever every callback did, so any |
| 6 | documentation was hand-written and rotting from the moment it was saved. |
| 7 | Here the workflow is COMPILED (object_governance.py): transitions and |
| 8 | guards from the schema, the gate the schema names, reactions from HANDLES |
| 9 | declarations, notify rules and schedules from data. This page renders that |
| 10 | compilation live, so the docs cannot disagree with the system -- they are |
| 11 | the system, read back. |
| 12 | |
| 13 | Per collection: the state machine drawn as SVG (server-side, zero JS |
| 14 | dependencies -- a diagram that needs a CDN is a diagram that breaks), |
| 15 | every transition with its guard, what gates writes, what reacts, what gets |
| 16 | composed, who gets notified, when the clock touches it, and where it |
| 17 | renders. Plus the Mermaid source in a copy block, because the same text |
| 18 | pastes into GitHub, docs, or a whiteboard tool. |
| 19 | |
| 20 | Signed-in users only: the picture of how money moves through a system is |
| 21 | itself information about the system. No per-collection secrets are shown |
| 22 | beyond what the schema API already exposes, but the assembled map deserves |
| 23 | the same courtesy as the data it describes. |
| 24 | """ |
| 25 | |
| 26 | import html |
| 27 | import math |
| 28 | import os |
| 29 | |
| 30 | import object_governance |
| 31 | import object_schemas |
| 32 | |
| 33 | _PAGE_ROOTS = None # objects run from the server's roots; governance reads the same |
| 34 | |
| 35 | |
| 36 | def _base_dir(): |
| 37 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 38 | |
| 39 | |
| 40 | def _esc(value): |
| 41 | return html.escape(str(value or "")) |
| 42 | |
| 43 | |
| 44 | def _state_svg(transitions): |
| 45 | """The state machine as a self-contained SVG. |
| 46 | |
| 47 | Hand-laid layout: states ring-positioned, edges as straight lines with |
| 48 | small labels. Deliberately simple -- a six-state machine reads fine on |
| 49 | a ring, and a machine too tangled for this picture is feedback about |
| 50 | the machine, not the renderer. |
| 51 | """ |
| 52 | if not transitions: |
| 53 | return "" |
| 54 | field, moves = next(iter(transitions.items())) |
| 55 | states = sorted({s for s in moves} | |
| 56 | {t["to"] for targets in moves.values() for t in targets if t["to"]}) |
| 57 | n = len(states) |
| 58 | if not n: |
| 59 | return "" |
| 60 | width, height = 640, max(300, 90 * n // 2 + 160) |
| 61 | cx, cy = width / 2, height / 2 |
| 62 | radius = min(cx, cy) - 70 |
| 63 | pos = {} |
| 64 | for i, state in enumerate(states): |
| 65 | angle = (2 * math.pi * i / n) - math.pi / 2 |
| 66 | pos[state] = (cx + radius * math.cos(angle), cy + radius * math.sin(angle)) |
| 67 | |
| 68 | parts = [f'<svg viewBox="0 0 {width} {height}" role="img" ' |
| 69 | f'style="max-width:100%;height:auto;background:var(--panel,#1a1a22);' |
| 70 | f'border:1px solid var(--line,#333);border-radius:8px">'] |
| 71 | parts.append('<defs><marker id="arr" markerWidth="8" markerHeight="8" refX="7" refY="3" ' |
| 72 | 'orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="currentColor"/></marker></defs>') |
| 73 | for state, targets in moves.items(): |
| 74 | x1, y1 = pos[state] |
| 75 | for target in targets: |
| 76 | if not target["to"] or target["to"] not in pos: |
| 77 | continue |
| 78 | x2, y2 = pos[target["to"]] |
| 79 | dx, dy = x2 - x1, y2 - y1 |
| 80 | dist = math.hypot(dx, dy) or 1 |
| 81 | # stop the line at the node's edge so the arrowhead is visible |
| 82 | sx, sy = x1 + dx / dist * 34, y1 + dy / dist * 34 |
| 83 | ex, ey = x2 - dx / dist * 38, y2 - dy / dist * 38 |
| 84 | parts.append(f'<line x1="{sx:.0f}" y1="{sy:.0f}" x2="{ex:.0f}" y2="{ey:.0f}" ' |
| 85 | f'stroke="currentColor" stroke-opacity="0.55" marker-end="url(#arr)"/>') |
| 86 | for state in states: |
| 87 | x, y = pos[state] |
| 88 | parts.append(f'<g><circle cx="{x:.0f}" cy="{y:.0f}" r="32" fill="none" ' |
| 89 | f'stroke="currentColor" stroke-opacity="0.9"/>' |
| 90 | f'<text x="{x:.0f}" y="{y:.0f}" text-anchor="middle" dominant-baseline="middle" ' |
| 91 | f'fill="currentColor" font-size="12">{_esc(state)}</text></g>') |
| 92 | parts.append(f'<text x="{width - 10}" y="{height - 10}" text-anchor="end" fill="currentColor" ' |
| 93 | f'fill-opacity="0.5" font-size="11">{_esc(field)}</text>') |
| 94 | parts.append("</svg>") |
| 95 | return "".join(parts) |
| 96 | |
| 97 | |
| 98 | def _rows(items, render): |
| 99 | return "".join(render(item) for item in items) or \ |
| 100 | '<tr><td colspan="9" class="muted">none</td></tr>' |
| 101 | |
| 102 | |
| 103 | def _collection_page(collection, base): |
| 104 | info = object_governance.governs(collection, base_dir=base) |
| 105 | mermaid = object_governance.workflow_mermaid(collection, base_dir=base) |
| 106 | decl = info["declarations"] |
| 107 | |
| 108 | transitions_rows = [] |
| 109 | for field, moves in decl["transitions"].items(): |
| 110 | for state, targets in moves.items(): |
| 111 | for target in targets: |
| 112 | guard = ", ".join(f"{k} = {v}" for k, v in (target["when"] or {}).items()) or "anyone with write access" |
| 113 | transitions_rows.append( |
| 114 | f"<tr><td><code>{_esc(state)}</code> → <code>{_esc(target['to'])}</code></td>" |
| 115 | f"<td>{_esc(guard)}</td></tr>") |
| 116 | body = f""" |
| 117 | <div class="breadcrumb"><a href="/">Home</a> / <a href="/flow">Flow</a> / {_esc(collection)}</div> |
| 118 | <h1>How <code>{_esc(collection)}</code> works</h1> |
| 119 | <p class="muted">Compiled from the schema, hooks, handlers and rules the server actually |
| 120 | enforces — this page cannot disagree with the system, because it is the system, read back.</p> |
| 121 | {_state_svg(decl["transitions"])} |
| 122 | <h2>Transitions & who may make them</h2> |
| 123 | <table><thead><tr><th>Move</th><th>Guard</th></tr></thead> |
| 124 | <tbody>{''.join(transitions_rows) or '<tr><td colspan="2" class="muted">no state machine — plain records</td></tr>'}</tbody></table> |
| 125 | <h2>Gates (before the write, fail closed)</h2> |
| 126 | <table><tbody>{_rows(info["gates"], lambda g: f"<tr><td><code>{_esc(g['object_id'])}</code></td><td>{_esc(g['note'])}</td></tr>")}</tbody></table> |
| 127 | <h2>Reactions (after the write, never block it)</h2> |
| 128 | <table><tbody>{_rows(info["reactions"], lambda r: f"<tr><td><code>{_esc(r['object_id'])}</code></td><td>on {_esc(r['on'])}</td></tr>")}</tbody></table> |
| 129 | <h2>Composes into</h2> |
| 130 | <table><tbody>{_rows(info["feeds"], lambda f: f"<tr><td><code>{_esc(f)}</code> <span class='muted'>(stamped generated_from)</span></td></tr>")}</tbody></table> |
| 131 | <h2>Notifications</h2> |
| 132 | <table><tbody>{_rows(info["notifications"], lambda n: f"<tr><td>{_esc(n['event'])}</td><td>{_esc(n['recipients'])}</td></tr>")}</tbody></table> |
| 133 | <h2>Derived fields</h2> |
| 134 | <table><tbody>{_rows(list(decl["formulas"].items()) + list(decl["rollups"].items()), lambda kv: f"<tr><td><code>{_esc(kv[0])}</code></td><td><code>{_esc(kv[1])}</code></td></tr>")}</tbody></table> |
| 135 | <h2>Rendered at</h2> |
| 136 | <table><tbody>{_rows(info["views"], lambda v: f"<tr><td><a href='{_esc(v['route'] or '')}'>{_esc(v['route'] or v['view'])}</a></td></tr>")}</tbody></table> |
| 137 | <h2>Mermaid source</h2> |
| 138 | <p class="muted">The same diagram as text — paste it into GitHub, docs, or any tool that speaks Mermaid.</p> |
| 139 | <pre style="overflow-x:auto">{_esc(mermaid)}</pre> |
| 140 | """ |
| 141 | return body |
| 142 | |
| 143 | |
| 144 | def _index_page(base): |
| 145 | items = [] |
| 146 | for summary in object_schemas.list_schemas(base_dir=base): |
| 147 | name = summary.get("name") or summary.get("collection") |
| 148 | if not name: |
| 149 | continue |
| 150 | items.append(f'<li><a href="/flow/{_esc(name)}"><code>{_esc(name)}</code></a></li>') |
| 151 | return f""" |
| 152 | <div class="breadcrumb"><a href="/">Home</a> / Flow</div> |
| 153 | <h1>How things work</h1> |
| 154 | <p class="muted">One page per collection: its state machine, who may move it, what gates |
| 155 | writes, what reacts, what gets composed, and where it renders — compiled live from |
| 156 | the declarations the server enforces. The docs most systems forgot, generated so they |
| 157 | cannot rot.</p> |
| 158 | <ul class="accountlist">{''.join(sorted(items))}</ul> |
| 159 | """ |
| 160 | |
| 161 | |
| 162 | def GET(request): |
| 163 | identity = request.get("_identity") or {} |
| 164 | if not identity.get("user_id"): |
| 165 | body = ('<p class="hint"><a href="/login?next=/flow">Sign in</a> to see how the ' |
| 166 | "system's collections work — their state machines, gates, and reactions.</p>") |
| 167 | else: |
| 168 | base = _base_dir() |
| 169 | collection = str(request.get("collection") or "").strip() |
| 170 | if collection and object_schemas.validate_schema_name(collection): |
| 171 | body = _collection_page(collection, base) |
| 172 | else: |
| 173 | body = _index_page(base) |
| 174 | |
| 175 | return {"content_type": "text/html; charset=utf-8", "body": f"""<!doctype html> |
| 176 | <html lang="en"> |
| 177 | <head> |
| 178 | <meta charset="utf-8"> |
| 179 | <meta name="viewport" content="width=device-width, initial-scale=1"> |
| 180 | <title>Flow</title> |
| 181 | <link rel="stylesheet" href="/style"> |
| 182 | <style> |
| 183 | .wrap {{ max-width: 900px; margin: 0 auto; padding: 1.25rem; }} |
| 184 | table {{ width: 100%; border-collapse: collapse; margin: 0.25rem 0 1rem; }} |
| 185 | td, th {{ text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid var(--line, #333); }} |
| 186 | h2 {{ font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted, #999); margin: 1.25rem 0 0.25rem; }} |
| 187 | .muted {{ color: var(--muted, #999); }} |
| 188 | svg {{ margin: 0.75rem 0; color: var(--text, #eee); }} |
| 189 | </style> |
| 190 | </head> |
| 191 | <body> |
| 192 | <script src="/nav"></script> |
| 193 | <div class="wrap">{body}</div> |
| 194 | </body> |
| 195 | </html>"""} |