Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3Dan's observation, which most web software never answered: apps forgot
4help, and frameworks forgot docs. The reason was structural -- their
5workflow existed only as the union of whatever every callback did, so any
6documentation was hand-written and rotting from the moment it was saved.
7Here the workflow is COMPILED (object_governance.py): transitions and
8guards from the schema, the gate the schema names, reactions from HANDLES
9declarations, notify rules and schedules from data. This page renders that
10compilation live, so the docs cannot disagree with the system -- they are
11the system, read back.
12
13Per collection: the state machine drawn as SVG (server-side, zero JS
14dependencies -- a diagram that needs a CDN is a diagram that breaks),
15every transition with its guard, what gates writes, what reacts, what gets
16composed, who gets notified, when the clock touches it, and where it
17renders. Plus the Mermaid source in a copy block, because the same text
18pastes into GitHub, docs, or a whiteboard tool.
19
20Signed-in users only: the picture of how money moves through a system is
21itself information about the system. No per-collection secrets are shown
22beyond what the schema API already exposes, but the assembled map deserves
23the same courtesy as the data it describes.
24"""
25
26import html
27import math
28import os
29
30import object_governance
31import object_schemas
32
33_PAGE_ROOTS = None # objects run from the server's roots; governance reads the same
34
35
36def _base_dir():
37 return os.environ.get("DBBASIC_DATA_DIR", "data")
38
39
40def _esc(value):
41 return html.escape(str(value or ""))
42
43
44def _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
98def _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
103def _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> &rarr; <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
120enforces &mdash; this page cannot disagree with the system, because it is the system, read back.</p>
121{_state_svg(decl["transitions"])}
122<h2>Transitions &amp; 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 &mdash; 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
144def _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
155writes, what reacts, what gets composed, and where it renders &mdash; compiled live from
156the declarations the server enforces. The docs most systems forgot, generated so they
157cannot rot.</p>
158<ul class="accountlist">{''.join(sorted(items))}</ul>
159"""
160
161
162def 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 &mdash; 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; }}
184table {{ width: 100%; border-collapse: collapse; margin: 0.25rem 0 1rem; }}
185td, th {{ text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid var(--line, #333); }}
186h2 {{ 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); }}
188svg {{ 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>"""}