Skip to content

The only tool you need to know what is happening and how to fix it.

more screenshots and diagrams

ddux8b18d472d941
diff --git a/.github/screenshots/endpoints.png b/.github/screenshots/endpoints.png
new file mode 100644
index 00000000..bcd55dbe
Binary files /dev/null and b/.github/screenshots/endpoints.png differ
diff --git a/.github/screenshots/issues.png b/.github/screenshots/issues.png
new file mode 100644
index 00000000..be01e856
Binary files /dev/null and b/.github/screenshots/issues.png differ
diff --git a/.github/screenshots/logs.png b/.github/screenshots/logs.png
new file mode 100644
index 00000000..52c981eb
Binary files /dev/null and b/.github/screenshots/logs.png differ
diff --git a/.github/screenshots/metrics.png b/.github/screenshots/metrics.png
new file mode 100644
index 00000000..4119c8fe
Binary files /dev/null and b/.github/screenshots/metrics.png differ
diff --git a/.github/screenshots/span-waterfall.png b/.github/screenshots/span-waterfall.png
new file mode 100644
index 00000000..d08c8468
Binary files /dev/null and b/.github/screenshots/span-waterfall.png differ
diff --git a/README.md b/README.md
index 8e265795..3550c2cf 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,12 @@ Traceway is an **OpenTelemetry-native** observability platform that combines **l
**MIT licensed. No BSL. No "open core."** Every feature is in the box. Self-host it for free, or run it on [Traceway Cloud](https://cloud.tracewayapp.com) if you'd rather not babysit infra.
-<img alt="Traceway Dashboard" src="./website/public/images/performance-endpoints-impact-table.png" />
+<table width="100%">
+<tr>
+<td width="50%" valign="top"><img alt="Traceway Issues" src="./.github/screenshots/issues.png" /></td>
+<td width="50%" valign="top"><img alt="Traceway Endpoints" src="./.github/screenshots/endpoints.png" /></td>
+</tr>
+</table>
<p align="center">
<a href="https://discord.gg/RZq9NT62nc"><b>πŸ‘‹ Join the Traceway Community on Discord β†’</b></a><br>
@@ -205,12 +210,12 @@ Traceway integrates with the tools you already use. Every integration ships trac
<table width="100%">
<tr>
-<td width="50%" valign="top"><b>Logs β€” trace-linked search</b><br><img src="./website/public/images/logs-search-and-detail.png" alt="Logs" /></td>
-<td width="50%" valign="top"><b>Span waterfall</b><br><img src="./website/public/images/traces-spans-waterfall.png" alt="Spans" /></td>
+<td width="50%" valign="top"><b>Logs β€” trace-linked search</b><br><img src="./.github/screenshots/logs.png" alt="Logs" /></td>
+<td width="50%" valign="top"><b>Span waterfall</b><br><img src="./.github/screenshots/span-waterfall.png" alt="Spans" /></td>
</tr>
<tr>
-<td width="50%" valign="top"><b>Metrics β€” application dashboard</b><br><img src="./website/public/images/metrics-application-dashboard.png" alt="Metrics" /></td>
-<td width="50%" valign="top"><b>Exceptions β€” grouped & ranked</b><br><img src="./website/public/images/exceptions-grouped-ranked.png" alt="Exceptions" /></td>
+<td width="50%" valign="top"><b>Metrics β€” application dashboard</b><br><img src="./.github/screenshots/metrics.png" alt="Metrics" /></td>
+<td width="50%" valign="top"><b>Exceptions β€” grouped & ranked</b><br><img src="./.github/screenshots/issues.png" alt="Exceptions" /></td>
</tr>
</table>
diff --git a/diagrams/architecture-diagram.drawio b/diagrams/architecture-diagram.drawio
index d3147e2c..449365ca 100644
--- a/diagrams/architecture-diagram.drawio
+++ b/diagrams/architecture-diagram.drawio
@@ -1,71 +1,110 @@
<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36" version="29.3.6">
<diagram name="Page-1" id="wy32oRJBnUYnc9i8Ji1n">
- <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0" adaptiveColors="auto">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
- <mxCell id="nGLuf51OtG82o4zcJS6--42" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--21">
- <mxGeometry relative="1" as="geometry" />
+ <mxCell id="dt-1" parent="1" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;verticalAlign=top;align=center;spacingTop=2;fontSize=11;" value="&lt;b&gt;Distributed Trace&lt;/b&gt; &amp;nbsp;&lt;i&gt;traces from any service that share a distributedTraceId are grouped together&lt;/i&gt;" vertex="1">
+ <mxGeometry height="150" width="640" x="105" y="40" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--48" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--46">
- <mxGeometry relative="1" as="geometry" />
+ <mxCell id="trace-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Trace" vertex="1">
+ <mxGeometry height="103" width="450" x="200" y="70" as="geometry" />
+ </mxCell>
+ <mxCell id="trace-2" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Endpoint&lt;/b&gt;&lt;br&gt;&lt;i&gt;GET /users/:id&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="135" x="11" y="31" as="geometry" />
+ </mxCell>
+ <mxCell id="trace-3" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="&lt;b&gt;Task&lt;/b&gt;&lt;br&gt;&lt;i&gt;send-notifications&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="135" x="157" y="31" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--3" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Trace" vertex="1">
- <mxGeometry height="103" width="270" x="186" y="79" as="geometry" />
+ <mxCell id="trace-4" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="&lt;b&gt;AI Trace&lt;/b&gt;&lt;br&gt;&lt;i&gt;chat claude-sonnet-5&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="135" x="303" y="31" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--4" parent="nGLuf51OtG82o4zcJS6--3" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Endpoint&lt;/b&gt;&lt;br&gt;&lt;i&gt;GET /users/:id&lt;/i&gt;" vertex="1">
+ <mxCell id="issue-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Issue" vertex="1">
+ <mxGeometry height="103" width="270" x="30" y="330" as="geometry" />
+ </mxCell>
+ <mxCell id="issue-2" parent="issue-1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Exception&lt;/b&gt;&lt;br&gt;&lt;i&gt;db failed to open&lt;/i&gt;" vertex="1">
<mxGeometry height="60" width="120" x="11" y="31" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--6" parent="nGLuf51OtG82o4zcJS6--3" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="&lt;b&gt;Task&lt;/b&gt;&lt;br&gt;&lt;i&gt;send-notifications&lt;/i&gt;" vertex="1">
+ <mxCell id="issue-3" parent="issue-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="&lt;b&gt;Message&lt;/b&gt;&lt;br&gt;&lt;i&gt;captured log text&lt;/i&gt;" vertex="1">
<mxGeometry height="60" width="120" x="139" y="31" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--41" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--21">
- <mxGeometry relative="1" as="geometry" />
+ <mxCell id="issue-4" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;" value="Occurrences are grouped into Issues by a normalized hash of the stack trace" vertex="1">
+ <mxGeometry height="30" width="270" x="30" y="437" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--8" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Issue" vertex="1">
- <mxGeometry height="103" width="270" x="12" y="274" as="geometry" />
+ <mxCell id="spans-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Spans" vertex="1">
+ <mxGeometry height="110" width="200" x="580" y="330" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--9" parent="nGLuf51OtG82o4zcJS6--8" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Exception&lt;/b&gt;&lt;br&gt;&lt;i&gt;db failed to open&lt;/i&gt;" vertex="1">
- <mxGeometry height="60" width="120" x="11" y="31" as="geometry" />
+ <mxCell id="spans-2" parent="spans-1" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Name: db.load.user&lt;div&gt;Started At: {time}&lt;br&gt;Duration: {time}&lt;br&gt;Parent Span: {span id}&lt;/div&gt;" vertex="1">
+ <mxGeometry height="70" width="176" x="12" y="30" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--10" parent="nGLuf51OtG82o4zcJS6--8" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="&lt;b&gt;Message&lt;/b&gt;&lt;div&gt;&lt;br/&gt;&lt;/div&gt;" vertex="1">
- <mxGeometry height="60" width="120" x="139" y="31" as="geometry" />
+ <mxCell id="spans-3" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;" value="Spans nest under each other via their Parent Span" vertex="1">
+ <mxGeometry height="30" width="220" x="570" y="444" as="geometry" />
+ </mxCell>
+ <mxCell id="attr-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Attributes" vertex="1">
+ <mxGeometry height="79" width="110" x="370" y="560" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--11" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;">
+ <mxCell id="attr-2" parent="attr-1" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Key: UserId&amp;nbsp;&lt;div&gt;Value: 10&lt;/div&gt;" vertex="1">
+ <mxGeometry height="42" width="90" x="12" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="e-issue" edge="1" parent="1" source="trace-1" target="issue-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
<mxGeometry relative="1" as="geometry">
<Array as="points">
- <mxPoint x="145" y="131" />
- <mxPoint x="145" y="275" />
+ <mxPoint x="165" y="121" />
+ <mxPoint x="165" y="280" />
</Array>
- <mxPoint x="145" y="274" as="targetPoint" />
</mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--12" connectable="0" parent="nGLuf51OtG82o4zcJS6--11" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Traces can have Issues&amp;nbsp;&lt;div&gt;attached to them&lt;/div&gt;" vertex="1">
- <mxGeometry relative="1" x="-0.497" y="3" as="geometry">
- <mxPoint x="-35" y="-26" as="offset" />
+ <mxCell id="e-issue-label" connectable="0" parent="e-issue" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Traces can have Issues attached&lt;div&gt;via &lt;i&gt;trace id + trace type&lt;/i&gt;&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">
+ <mxPoint x="-60" y="-40" as="offset" />
</mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--21" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Attributes" vertex="1">
- <mxGeometry height="79" width="104" x="269" y="437" as="geometry" />
+ <mxCell id="e-spans" edge="1" parent="1" source="trace-1" target="spans-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="680" y="121" />
+ <mxPoint x="680" y="280" />
+ </Array>
+ </mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--39" parent="nGLuf51OtG82o4zcJS6--21" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Key: UserId&amp;nbsp;&lt;div&gt;Value: 10&lt;/div&gt;" vertex="1">
- <mxGeometry height="42" width="106" x="15" y="30" as="geometry" />
+ <mxCell id="e-spans-label" connectable="0" parent="e-spans" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have multiple Spans" vertex="1">
+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">
+ <mxPoint x="63" y="-40" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e-attr" edge="1" parent="1" source="trace-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--44" connectable="0" parent="1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have&amp;nbsp;&lt;div&gt;multiple Attributes&lt;/div&gt;" vertex="1">
- <mxGeometry x="377" y="305" as="geometry">
- <mxPoint x="-8" y="4" as="offset" />
+ <mxCell id="e-attr-label" connectable="0" parent="e-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have&lt;div&gt;multiple Attributes&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="0.55" y="0" as="geometry">
+ <mxPoint x="1" y="0" as="offset" />
</mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--45" connectable="0" parent="1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="An Issue can have&amp;nbsp;&lt;div&gt;multiple additional Attributes&lt;/div&gt;" vertex="1">
- <mxGeometry x="131" y="494" as="geometry">
- <mxPoint x="-8" y="4" as="offset" />
+ <mxCell id="e-issue-attr" edge="1" parent="1" source="issue-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="335" y="382" />
+ <mxPoint x="335" y="600" />
+ </Array>
</mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--46" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Spans" vertex="1">
- <mxGeometry height="93" width="198" x="460" y="271" as="geometry" />
+ <mxCell id="e-issue-attr-label" connectable="0" parent="e-issue-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="An Issue can have&lt;div&gt;multiple additional Attributes&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="0.5" y="0" as="geometry">
+ <mxPoint x="-78" y="0" as="offset" />
+ </mxGeometry>
</mxCell>
- <mxCell id="nGLuf51OtG82o4zcJS6--47" parent="nGLuf51OtG82o4zcJS6--46" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Name:db.load.user&lt;div&gt;Started At: {time}&lt;br&gt;Duration: {time}&lt;/div&gt;" vertex="1">
- <mxGeometry height="54" width="174" x="15" y="30" as="geometry" />
+ <mxCell id="e-spans-attr" edge="1" parent="1" source="spans-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="520" y="385" />
+ <mxPoint x="520" y="600" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e-spans-attr-label" connectable="0" parent="e-spans-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Spans can have&lt;div&gt;Attributes as well&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="0.5" y="0" as="geometry">
+ <mxPoint x="62" y="0" as="offset" />
+ </mxGeometry>
</mxCell>
</root>
</mxGraphModel>
diff --git a/diagrams/architecture.png b/diagrams/architecture.png
index 131eecd8..79cc3eaa 100644
Binary files a/diagrams/architecture.png and b/diagrams/architecture.png differ
diff --git a/diagrams/auth-types.drawio b/diagrams/auth-types.drawio
new file mode 100644
index 00000000..e069e910
--- /dev/null
+++ b/diagrams/auth-types.drawio
@@ -0,0 +1,158 @@
+<mxfile host="app.diagrams.net" version="29.3.6">
+ <diagram name="Page-1" id="auth-types-1">
+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1650" pageHeight="720" math="0" shadow="0" adaptiveColors="auto">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="sdk" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;App with Traceway SDK&lt;br&gt;or OTel exporter&lt;/b&gt;" vertex="1">
+ <mxGeometry height="60" width="170" x="40" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="ci" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Build / CI&lt;/b&gt;&lt;br&gt;&lt;i&gt;symbol upload&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="170" x="40" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="user" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Dashboard user&lt;/b&gt;&lt;br&gt;&lt;i&gt;browser&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="170" x="40" y="280" as="geometry" />
+ </mxCell>
+ <mxCell id="cli" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;traceway CLI&lt;/b&gt;" vertex="1">
+ <mxGeometry height="60" width="170" x="40" y="470" as="geometry" />
+ </mxCell>
+ <mxCell id="mcp" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;MCP client&lt;/b&gt;" vertex="1">
+ <mxGeometry height="60" width="170" x="40" y="600" as="geometry" />
+ </mxCell>
+ <mxCell id="ptok" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Project token&lt;/b&gt;&lt;br&gt;&lt;i&gt;non-expiring, per project&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="220" x="280" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="smtok" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Source map token&lt;/b&gt;&lt;br&gt;&lt;i&gt;non-expiring, per project&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="220" x="280" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="jwt" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Dashboard JWT&lt;/b&gt;&lt;br&gt;&lt;i&gt;7 days&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="280" y="260" as="geometry" />
+ </mxCell>
+ <mxCell id="pat" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Personal access token twp_&lt;/b&gt;&lt;br&gt;&lt;i&gt;SHA-256 hashed, optional expiry&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="220" x="280" y="340" as="geometry" />
+ </mxCell>
+ <mxCell id="devflow" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Device flow (RFC 8628)&lt;/b&gt;&lt;br&gt;&lt;i&gt;user approves the&lt;br&gt;user code at /device&lt;/i&gt;" vertex="1">
+ <mxGeometry height="80" width="220" x="280" y="460" as="geometry" />
+ </mxCell>
+ <mxCell id="oauth" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;OAuth code + PKCE&lt;/b&gt;&lt;br&gt;&lt;i&gt;RFC 7591 dynamic registration,&lt;br&gt;consent at /oauth/authorize,&lt;br&gt;single-use twa_ code (5 min)&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="220" x="280" y="580" as="geometry" />
+ </mxCell>
+ <mxCell id="tokend" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;POST /api/auth/token&lt;/b&gt;&lt;br&gt;&lt;i&gt;device_code, authorization_code,&lt;br&gt;refresh_token grants&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="200" x="560" y="520" as="geometry" />
+ </mxCell>
+ <mxCell id="acc" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Access token&lt;/b&gt;&lt;br&gt;&lt;i&gt;15-min JWT&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="200" x="820" y="450" as="geometry" />
+ </mxCell>
+ <mxCell id="ref" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Refresh token twr_&lt;/b&gt;&lt;br&gt;&lt;i&gt;90 days, rotating, family&lt;br&gt;revoked on reuse&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="200" x="820" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="uca" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;UseClientAuth&lt;/b&gt;" vertex="1">
+ <mxGeometry height="50" width="190" x="1090" y="45" as="geometry" />
+ </mxCell>
+ <mxCell id="usma" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;UseSourceMapAuth&lt;/b&gt;" vertex="1">
+ <mxGeometry height="50" width="190" x="1090" y="155" as="geometry" />
+ </mxCell>
+ <mxCell id="uaa" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;UseAppAuth&lt;/b&gt;&lt;br&gt;&lt;i&gt;JWT or twp_ hash lookup&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="190" x="1090" y="300" as="geometry" />
+ </mxCell>
+ <mxCell id="roles" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;Role middleware&lt;/b&gt;&lt;br&gt;&lt;i&gt;RequireProjectAccess&lt;br&gt;RequireWriteAccess (blocks readonly)&lt;br&gt;RequireAdminAccess (owner, admin)&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="190" x="1090" y="410" as="geometry" />
+ </mxCell>
+ <mxCell id="ingest" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Telemetry ingestion&lt;/b&gt;&lt;br&gt;&lt;i&gt;/api/report, /api/otel/v1/*,&lt;br&gt;/api/profiles/ingest&lt;/i&gt;" vertex="1">
+ <mxGeometry height="80" width="240" x="1340" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="symup" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Symbol uploads&lt;/b&gt;&lt;br&gt;&lt;i&gt;/api/sourcemaps/upload,&lt;br&gt;/api/symbols/upload&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="240" x="1340" y="145" as="geometry" />
+ </mxCell>
+ <mxCell id="app" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Dashboard API + MCP server&lt;/b&gt;&lt;br&gt;&lt;i&gt;scoped by organization role&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="240" x="1340" y="320" as="geometry" />
+ </mxCell>
+ <mxCell id="e1" edge="1" parent="1" source="sdk" target="ptok" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e2" edge="1" parent="1" source="ptok" target="uca" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e3" edge="1" parent="1" source="uca" target="ingest" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e4" edge="1" parent="1" source="ci" target="smtok" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e5" edge="1" parent="1" source="smtok" target="usma" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e6" edge="1" parent="1" source="usma" target="symup" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e7" edge="1" parent="1" source="user" target="jwt" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e7l" connectable="0" parent="e7" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="login / SSO" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e8" edge="1" parent="1" source="user" target="pat" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e8l" connectable="0" parent="e8" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="account page" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="0" y="10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e9" edge="1" parent="1" source="jwt" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.35;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e10" edge="1" parent="1" source="pat" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.65;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e11" edge="1" parent="1" source="cli" target="devflow" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e12" edge="1" parent="1" source="mcp" target="oauth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e13" edge="1" parent="1" source="devflow" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.25;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e14" edge="1" parent="1" source="oauth" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e15" edge="1" parent="1" source="tokend" target="acc" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e16" edge="1" parent="1" source="tokend" target="ref" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e17" edge="1" parent="1" source="ref" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;dashed=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="920" y="660" />
+ <mxPoint x="660" y="660" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e17l" connectable="0" parent="e17" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="rotate" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e18" edge="1" parent="1" source="acc" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.25;entryY=1;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="920" y="385" />
+ <mxPoint x="1137" y="385" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="e19" edge="1" parent="1" source="uaa" target="roles" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.6;exitY=1;exitDx=0;exitDy=0;entryX=0.6;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="e20" edge="1" parent="1" source="roles" target="app" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/diagrams/auth-types.png b/diagrams/auth-types.png
new file mode 100644
index 00000000..c5115750
Binary files /dev/null and b/diagrams/auth-types.png differ
diff --git a/diagrams/db-architecture.drawio b/diagrams/db-architecture.drawio
new file mode 100644
index 00000000..e3b19f47
--- /dev/null
+++ b/diagrams/db-architecture.drawio
@@ -0,0 +1,117 @@
+<mxfile host="app.diagrams.net" version="29.3.6">
+ <diagram name="Page-1" id="db-architecture-1">
+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1500" pageHeight="1050" math="0" shadow="0" adaptiveColors="auto">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="consumers" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Controllers, services, workers&lt;/b&gt;&lt;br&gt;&lt;i&gt;import the facade packages only: transactional.UserRepository, telemetry.SpanRepository, never a backend package directly&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="1180" x="200" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="lmain" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=28;" value="Main DB: db.DB (relational / config)" vertex="1">
+ <mxGeometry height="330" width="600" x="80" y="170" as="geometry" />
+ </mxCell>
+ <mxCell id="lfac" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;repositories/transactional facade&lt;/b&gt;&lt;br&gt;&lt;i&gt;transactional_sqlite.go (default) | transactional_pg.go (-tags transactional_pg)&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="560" x="20" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="lchar" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;align=left;spacingLeft=8;spacingRight=8;" value="&lt;b&gt;Transactions required:&lt;/b&gt; middleware.Transactional / db.ExecuteTransaction (*sql.Tx)&lt;br&gt;&lt;i&gt;users, organizations, projects, invitations, widgets, metric_registry, notification config, personal_access_tokens, refresh_tokens, device_authorizations&lt;/i&gt;&lt;br&gt;&lt;i&gt;pg/ and sqlite/ are dialect-neutral twins, parity_test.go enforces byte-for-byte equality&lt;/i&gt;" vertex="1">
+ <mxGeometry height="105" width="560" x="20" y="115" as="geometry" />
+ </mxCell>
+ <mxCell id="limp1" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;sqlite/&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="170" x="20" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="limp2" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;pg/&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="170" x="210" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="limp3" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;shared/&lt;/b&gt;&lt;br&gt;&lt;i&gt;token hashing,&lt;br&gt;facade structs&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="180" x="400" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="rtel" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=28;" value="Telemetry DB: db.TelemetryDB (append-only telemetry)" vertex="1">
+ <mxGeometry height="330" width="680" x="740" y="170" as="geometry" />
+ </mxCell>
+ <mxCell id="rfac" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;repositories/telemetry facade&lt;/b&gt;&lt;br&gt;&lt;i&gt;telemetry_sqlite.go (default) | telemetry_duckdb.go (-tags telemetry_duckdb) | telemetry_ch.go (-tags telemetry_ch)&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="640" x="20" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="rchar" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;align=left;spacingLeft=8;spacingRight=8;" value="&lt;b&gt;No transactions:&lt;/b&gt; batch InsertAsync only (ClickHouse PrepareBatch / DuckDB Appender / direct lit inserts)&lt;br&gt;&lt;i&gt;endpoints, tasks, ai_traces, spans, exception_stack_traces, metric_points, log_records, sessions, session_recordings, profiles, fired_notifications, archived_exceptions, slow_endpoints&lt;/i&gt;" vertex="1">
+ <mxGeometry height="105" width="640" x="20" y="115" as="geometry" />
+ </mxCell>
+ <mxCell id="rimp1" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;sqlite/&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="115" x="20" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="rimp2" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;duckdb/&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="115" x="150" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="rimp3" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;clickhouse/&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="120" x="280" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="rimp4" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=10;" value="&lt;b&gt;sqlitetypes/&lt;/b&gt;&lt;br&gt;&lt;i&gt;scan types for&lt;br&gt;sqlite + duckdb&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="115" x="415" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="rimp5" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=10;" value="&lt;b&gt;shared/&lt;/b&gt;&lt;br&gt;&lt;i&gt;helpers for all&lt;br&gt;backends&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="115" x="545" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="engsm" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;SQLite (main)&lt;/b&gt;&lt;br&gt;&lt;i&gt;SQLITE_PATH, default ./traceway.db&lt;br&gt;no credentials, single file&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="280" x="80" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="engpg" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;PostgreSQL (main)&lt;/b&gt;&lt;br&gt;&lt;i&gt;POSTGRES_HOST / PORT / DATABASE /&lt;br&gt;USERNAME / PASSWORD / SSLMODE&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="290" x="390" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="engst" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;SQLite (telemetry)&lt;/b&gt;&lt;br&gt;&lt;i&gt;traceway_telemetry.db,&lt;br&gt;derived from SQLITE_PATH&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="215" x="740" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="engdd" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;DuckDB (telemetry)&lt;/b&gt;&lt;br&gt;&lt;i&gt;traceway_telemetry.duckdb&lt;br&gt;DUCKDB_MEMORY_LIMIT / THREADS /&lt;br&gt;CHECKPOINT_THRESHOLD&lt;br&gt;CGO required, glibc only&lt;/i&gt;" vertex="1">
+ <mxGeometry height="100" width="225" x="975" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="engch" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;ClickHouse (telemetry)&lt;/b&gt;&lt;br&gt;&lt;i&gt;CLICKHOUSE_SERVER / DATABASE /&lt;br&gt;USERNAME / PASSWORD / TLS&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="200" x="1220" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="combos" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=10;spacingRight=10;fontSize=11;" value="&lt;b&gt;Supported build combinations (2 build-tag axes: relational store + telemetry store)&lt;/b&gt;&lt;br&gt;&lt;br&gt;1. &lt;b&gt;no tags&lt;/b&gt;: SQLite + SQLite (zero-config self-hosted default)&lt;br&gt;2. &lt;b&gt;-tags telemetry_duckdb&lt;/b&gt;: SQLite main + DuckDB telemetry (columnar reads, Dockerfile.duckdb, Debian image)&lt;br&gt;3. &lt;b&gt;-tags &amp;quot;transactional_pg telemetry_ch&amp;quot;&lt;/b&gt;: PostgreSQL + ClickHouse (cloud / high volume)&lt;br&gt;&lt;br&gt;&lt;i&gt;Any other combination fails to compile: guard files in backend/app/db/ (guard_pg_without_ch.go, guard_ch_without_pg.go, guard_ch_and_duckdb.go, guard_stale_*.go)&lt;/i&gt;" vertex="1">
+ <mxGeometry height="190" width="600" x="80" y="710" as="geometry" />
+ </mxCell>
+ <mxCell id="tree" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=12;spacingRight=8;fontSize=11;fontFamily=Courier New;" value="&lt;b&gt;Folder structure: backend/app/&lt;/b&gt;&lt;br&gt;&lt;br&gt;db/ &amp;nbsp;.................. connections + build-tag guard files&lt;br&gt;migrations/&lt;br&gt;&amp;nbsp;&amp;nbsp;pg/ (transactional_pg) &amp;nbsp;&amp;nbsp;ch/ (telemetry_ch)&lt;br&gt;&amp;nbsp;&amp;nbsp;sqlite/ + sqlite_telemetry/ (default)&lt;br&gt;&amp;nbsp;&amp;nbsp;duckdb_telemetry/ (telemetry_duckdb)&lt;br&gt;repositories/&lt;br&gt;&amp;nbsp;&amp;nbsp;transactional/ ..... facade: transactional_{sqlite,pg}.go&lt;br&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;pg/ &amp;nbsp;sqlite/ &amp;nbsp;shared/&lt;br&gt;&amp;nbsp;&amp;nbsp;telemetry/ ......... facade: telemetry_{sqlite,duckdb,ch}.go&lt;br&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;clickhouse/ &amp;nbsp;duckdb/ &amp;nbsp;sqlite/ &amp;nbsp;shared/ &amp;nbsp;sqlitetypes/" vertex="1">
+ <mxGeometry height="230" width="680" x="740" y="710" as="geometry" />
+ </mxCell>
+ <mxCell id="ec1" edge="1" parent="1" source="consumers" target="lfac" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.15;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ec1l" connectable="0" parent="ec1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="transactions (*sql.Tx)" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="-75" y="0" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="ec2" edge="1" parent="1" source="consumers" target="rfac" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.85;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ec2l" connectable="0" parent="ec2" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="batch InsertAsync + reads" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="85" y="0" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="ee1" edge="1" parent="1" source="limp1" target="engsm" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ee2" edge="1" parent="1" source="limp2" target="engpg" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ee3" edge="1" parent="1" source="rimp1" target="engst" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ee4" edge="1" parent="1" source="rimp2" target="engdd" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.4;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="947" y="520" />
+ <mxPoint x="1065" y="520" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="ee5" edge="1" parent="1" source="rimp3" target="engch" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="1080" y="535" />
+ <mxPoint x="1320" y="535" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/diagrams/db-architecture.png b/diagrams/db-architecture.png
new file mode 100644
index 00000000..67ecceee
Binary files /dev/null and b/diagrams/db-architecture.png differ
diff --git a/diagrams/ingestion-flows.drawio b/diagrams/ingestion-flows.drawio
new file mode 100644
index 00000000..a5a87e59
--- /dev/null
+++ b/diagrams/ingestion-flows.drawio
@@ -0,0 +1,185 @@
+<mxfile host="app.diagrams.net" version="29.3.6">
+ <diagram name="Page-1" id="ingestion-flows-1">
+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1650" pageHeight="700" math="0" shadow="0" adaptiveColors="auto">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="cA" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Traceway SDK clients" vertex="1">
+ <mxGeometry height="250" width="240" x="40" y="60" as="geometry" />
+ </mxCell>
+ <mxCell id="cA1" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;JS SDKs&lt;/b&gt;&lt;br&gt;&lt;i&gt;React, Svelte, Vue, Next.js,&lt;br&gt;React Native&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="200" x="20" y="38" as="geometry" />
+ </mxCell>
+ <mxCell id="cA2" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Mobile SDKs&lt;/b&gt;&lt;br&gt;&lt;i&gt;iOS, Android, Flutter&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="200" x="20" y="110" as="geometry" />
+ </mxCell>
+ <mxCell id="cA3" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Go SDK&lt;/b&gt;&lt;br&gt;&lt;i&gt;gin, chi, fiber, stdlib&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="200" x="20" y="182" as="geometry" />
+ </mxCell>
+ <mxCell id="cB" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="OpenTelemetry clients" vertex="1">
+ <mxGeometry height="180" width="240" x="40" y="360" as="geometry" />
+ </mxCell>
+ <mxCell id="cB1" parent="cB" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;OTel-instrumented backends&lt;/b&gt;&lt;br&gt;&lt;i&gt;Laravel, Django, NestJS,&lt;br&gt;Hono, Workers, ...&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="200" x="20" y="38" as="geometry" />
+ </mxCell>
+ <mxCell id="cB2" parent="cB" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Traceway OTel Agent&lt;/b&gt;&lt;br&gt;&lt;i&gt;host metrics&lt;/i&gt;" vertex="1">
+ <mxGeometry height="50" width="200" x="20" y="118" as="geometry" />
+ </mxCell>
+ <mxCell id="report" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;POST /api/report&lt;/b&gt;&lt;br&gt;&lt;i&gt;gzipped JSON&lt;br&gt;collection frames&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="190" x="340" y="130" as="geometry" />
+ </mxCell>
+ <mxCell id="otlp" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;POST /api/otel/v1/*&lt;/b&gt;&lt;br&gt;&lt;i&gt;traces, metrics, logs, profiles&lt;br&gt;protobuf or JSON, gzip&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="190" x="340" y="400" as="geometry" />
+ </mxCell>
+ <mxCell id="auth" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="&lt;b&gt;Project token auth&lt;/b&gt;&lt;br&gt;&lt;br&gt;&lt;i&gt;Authorization:&lt;br&gt;Bearer&lt;br&gt;&amp;lt;project token&amp;gt;&lt;/i&gt;" vertex="1">
+ <mxGeometry height="400" width="110" x="585" y="110" as="geometry" />
+ </mxCell>
+ <mxCell id="pA" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Report pipeline" vertex="1">
+ <mxGeometry height="250" width="300" x="750" y="60" as="geometry" />
+ </mxCell>
+ <mxCell id="frame" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Parse collection frames&lt;/b&gt;&lt;br&gt;&lt;i&gt;traces, stackTraces, metrics,&lt;br&gt;sessions, recordings&lt;/i&gt;" vertex="1">
+ <mxGeometry height="60" width="260" x="20" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="split" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Traces + nested spans&lt;/b&gt;&lt;br&gt;&lt;i&gt;isTask ? Task : Endpoint&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="260" x="20" y="110" as="geometry" />
+ </mxCell>
+ <mxCell id="recq" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Recording uploader&lt;/b&gt;&lt;br&gt;&lt;i&gt;bounded queue + workers&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="260" x="20" y="180" as="geometry" />
+ </mxCell>
+ <mxCell id="pB" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="OTel pipeline" vertex="1">
+ <mxGeometry height="250" width="300" x="750" y="360" as="geometry" />
+ </mxCell>
+ <mxCell id="class" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=8;" value="&lt;b&gt;Span classifier&lt;/b&gt;&lt;br&gt;&lt;i&gt;HTTP SERVER span &#8594; Endpoint&lt;br&gt;CONSUMER / console.command &#8594; Task&lt;br&gt;gen_ai.* attributes &#8594; AI Trace&lt;br&gt;other spans &#8594; Spans&lt;/i&gt;" vertex="1">
+ <mxGeometry height="95" width="260" x="20" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="evexc" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Exceptions&lt;/b&gt;&lt;br&gt;&lt;i&gt;from span events + exception.* attrs&lt;/i&gt;" vertex="1">
+ <mxGeometry height="50" width="260" x="20" y="142" as="geometry" />
+ </mxCell>
+ <mxCell id="conv" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Metric / log / profile converters&lt;/b&gt;" vertex="1">
+ <mxGeometry height="40" width="260" x="20" y="200" as="geometry" />
+ </mxCell>
+ <mxCell id="sym" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Symbolication at ingest&lt;/b&gt;&lt;br&gt;&lt;i&gt;JS, Dart, iOS, Android&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="190" x="1110" y="240" as="geometry" />
+ </mxCell>
+ <mxCell id="hash" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Normalized stack-trace hash&lt;/b&gt;&lt;br&gt;&lt;i&gt;groups occurrences into Issues&lt;/i&gt;" vertex="1">
+ <mxGeometry height="70" width="190" x="1110" y="350" as="geometry" />
+ </mxCell>
+ <mxCell id="store" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Telemetry store&lt;/b&gt;&lt;br&gt;&lt;i&gt;ClickHouse / SQLite / DuckDB&lt;/i&gt;&lt;br&gt;&lt;br&gt;&lt;i&gt;endpoints, tasks, ai_traces,&lt;br&gt;spans, exception_stack_traces,&lt;br&gt;metric_points, log_records,&lt;br&gt;sessions, profiles&lt;/i&gt;" vertex="1">
+ <mxGeometry height="170" width="230" x="1380" y="80" as="geometry" />
+ </mxCell>
+ <mxCell id="blob" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Object storage&lt;/b&gt;&lt;br&gt;&lt;i&gt;S3 / local disk&lt;/i&gt;&lt;br&gt;&lt;br&gt;&lt;i&gt;recording segments,&lt;br&gt;AI conversations&lt;/i&gt;" vertex="1">
+ <mxGeometry height="110" width="230" x="1380" y="430" as="geometry" />
+ </mxCell>
+ <mxCell id="eA" edge="1" parent="1" source="cA" target="report" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eB" edge="1" parent="1" source="cB" target="otlp" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eR2A" edge="1" parent="1" source="report" target="auth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.15;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eO2A" edge="1" parent="1" source="otlp" target="auth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.85;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eA2RP" edge="1" parent="1" source="auth" target="pA" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.15;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eA2OP" edge="1" parent="1" source="auth" target="pB" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.85;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eF2S" edge="1" parent="pA" source="frame" target="split" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eC2E" edge="1" parent="pB" source="class" target="evexc" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eSTACK" edge="1" parent="1" source="frame" target="sym" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.3;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="1065" y="125" />
+ <mxPoint x="1065" y="261" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eSTACKl" connectable="0" parent="eSTACK" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="stack traces" vertex="1">
+ <mxGeometry relative="1" x="-0.85" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eEVEXC" edge="1" parent="1" source="evexc" target="sym" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="1090" y="527" />
+ <mxPoint x="1090" y="289" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eEVEXCl" connectable="0" parent="eEVEXC" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="raw stacks" vertex="1">
+ <mxGeometry relative="1" x="-0.6" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eSYM2H" edge="1" parent="1" source="sym" target="hash" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eH2STORE" edge="1" parent="1" source="hash" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.15;entryY=1;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="1414" y="385" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eH2STOREl" connectable="0" parent="eH2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="exceptions" vertex="1">
+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eRP2STORE" edge="1" parent="1" source="pA" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.35;exitDx=0;exitDy=0;entryX=0;entryY=0.35;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eRP2STOREl" connectable="0" parent="eRP2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="endpoints, tasks, spans,&lt;div&gt;metrics, sessions&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="0.15" y="0" as="geometry">
+ <mxPoint x="0" y="-20" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eRECQ" edge="1" parent="1" source="recq" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.2;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="1075" y="267" />
+ <mxPoint x="1075" y="332" />
+ <mxPoint x="1426" y="332" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eRECQl" connectable="0" parent="eRECQ" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="recording segments" vertex="1">
+ <mxGeometry relative="1" x="0.35" y="0" as="geometry">
+ <mxPoint x="40" y="12" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eO2STORE" edge="1" parent="1" source="pB" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry">
+ <Array as="points">
+ <mxPoint x="900" y="640" />
+ <mxPoint x="1630" y="640" />
+ <mxPoint x="1630" y="165" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eO2STOREl" connectable="0" parent="eO2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="endpoints, tasks, ai_traces, spans,&lt;div&gt;metrics, logs, profiles&lt;/div&gt;" vertex="1">
+ <mxGeometry relative="1" x="-0.35" y="0" as="geometry">
+ <mxPoint x="0" y="-16" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="eO2BLOB" edge="1" parent="1" source="pB" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.8;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eO2BLOBl" connectable="0" parent="eO2BLOB" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="AI conversations" vertex="1">
+ <mxGeometry relative="1" x="-0.2" y="0" as="geometry">
+ <mxPoint x="0" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/diagrams/ingestion-flows.png b/diagrams/ingestion-flows.png
new file mode 100644
index 00000000..94c41355
Binary files /dev/null and b/diagrams/ingestion-flows.png differ
diff --git a/diagrams/symbolication-flows.drawio b/diagrams/symbolication-flows.drawio
new file mode 100644
index 00000000..85e2b663
--- /dev/null
+++ b/diagrams/symbolication-flows.drawio
@@ -0,0 +1,123 @@
+<mxfile host="app.diagrams.net" version="29.3.6">
+ <diagram name="Page-1" id="symbolication-flows-1">
+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1100" pageHeight="850" math="0" shadow="0" adaptiveColors="auto">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="up" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Symbol upload from build / CI (source map token)" vertex="1">
+ <mxGeometry height="190" width="980" x="40" y="40" as="geometry" />
+ </mxCell>
+ <mxCell id="jsa" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;JS source maps&lt;/b&gt;&lt;br&gt;&lt;i&gt;.js + .map files&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="20" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="iosa" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;iOS dSYM&lt;/b&gt;&lt;br&gt;&lt;i&gt;Mach-O DWARF, per-arch UUIDs&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="255" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="anda" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Android R8&lt;/b&gt;&lt;br&gt;&lt;i&gt;mapping.txt + proguard UUID&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="490" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="darta" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Flutter / Dart&lt;/b&gt;&lt;br&gt;&lt;i&gt;.symbols ELF + arch&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="725" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="up1" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;POST /api/sourcemaps/upload&lt;/b&gt;" vertex="1">
+ <mxGeometry height="45" width="220" x="20" y="125" as="geometry" />
+ </mxCell>
+ <mxCell id="up2" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;POST /api/symbols/upload&lt;/b&gt;" vertex="1">
+ <mxGeometry height="45" width="220" x="490" y="125" as="geometry" />
+ </mxCell>
+ <mxCell id="eu1" edge="1" parent="up" source="jsa" target="up1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eu2" edge="1" parent="up" source="iosa" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.25;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eu3" edge="1" parent="up" source="anda" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eu4" edge="1" parent="up" source="darta" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="blob" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=12;" value="&lt;b&gt;Object storage (S3 / local disk)&lt;/b&gt;&lt;br&gt;&lt;i&gt;sourcemaps/&amp;lt;project&amp;gt;/&amp;lt;file&amp;gt; + by-debug-id/&amp;lt;debugId&amp;gt;&lt;br&gt;iossymbols/&amp;lt;project&amp;gt;/&amp;lt;uuid&amp;gt;.dsym&lt;br&gt;androidmappings/&amp;lt;project&amp;gt;/&amp;lt;proguardUuid&amp;gt;.txt&lt;br&gt;dartsymbols/&amp;lt;project&amp;gt;/&amp;lt;buildId&amp;gt;-&amp;lt;arch&amp;gt;.symbols&lt;/i&gt;" vertex="1">
+ <mxGeometry height="120" width="560" x="250" y="290" as="geometry" />
+ </mxCell>
+ <mxCell id="tw" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Precompiled .tw lookup blobs&lt;/b&gt;&lt;br&gt;&lt;i&gt;built on first miss, stored&lt;br&gt;next to the artifact&lt;/i&gt;" vertex="1">
+ <mxGeometry height="90" width="220" x="850" y="305" as="geometry" />
+ </mxCell>
+ <mxCell id="cache" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;LRU cache&lt;/b&gt;&lt;br&gt;&lt;i&gt;in-memory (default)&lt;br&gt;or mmap disk cache&lt;/i&gt;" vertex="1">
+ <mxGeometry height="80" width="220" x="850" y="440" as="geometry" />
+ </mxCell>
+ <mxCell id="eb1" edge="1" parent="1" source="up1" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.1;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="eb2" edge="1" parent="1" source="up2" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.7;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ebt" edge="1" parent="1" source="blob" target="tw" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="etc" edge="1" parent="1" source="tw" target="cache" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ing" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Exception ingest (/api/report + OTLP)" vertex="1">
+ <mxGeometry height="250" width="1030" x="40" y="560" as="geometry" />
+ </mxCell>
+ <mxCell id="exc" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Exception arrives&lt;/b&gt;&lt;br&gt;&lt;i&gt;raw stack trace&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="200" x="20" y="45" as="geometry" />
+ </mxCell>
+ <mxCell id="pick" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Resolver chosen by&lt;br&gt;project framework&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="200" x="20" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="match" parent="ing" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=24;fontStyle=2;" value="Frame &#8594; artifact matching" vertex="1">
+ <mxGeometry height="90" width="760" x="250" y="35" as="geometry" />
+ </mxCell>
+ <mxCell id="mjs" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;JS&lt;/b&gt;&lt;br&gt;debug id, then&lt;br&gt;file basename" vertex="1">
+ <mxGeometry height="52" width="175" x="10" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="mios" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;iOS&lt;/b&gt;&lt;br&gt;binary image&lt;br&gt;UUID + offset" vertex="1">
+ <mxGeometry height="52" width="175" x="197" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="mand" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;Android&lt;/b&gt;&lt;br&gt;proguard UUID&lt;br&gt;from the report" vertex="1">
+ <mxGeometry height="52" width="175" x="384" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="mdart" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="&lt;b&gt;Dart&lt;/b&gt;&lt;br&gt;build id + arch&lt;br&gt;from the trace" vertex="1">
+ <mxGeometry height="52" width="175" x="571" y="30" as="geometry" />
+ </mxCell>
+ <mxCell id="resolved" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Symbolicated stack trace&lt;/b&gt;" vertex="1">
+ <mxGeometry height="55" width="230" x="250" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="ehash" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;Normalized hash&lt;/b&gt;&lt;br&gt;&lt;i&gt;computed after symbolication&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="230" x="520" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="ins" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;b&gt;exception_stack_traces&lt;/b&gt;&lt;br&gt;&lt;i&gt;grouped into Issues&lt;/i&gt;" vertex="1">
+ <mxGeometry height="55" width="220" x="790" y="150" as="geometry" />
+ </mxCell>
+ <mxCell id="note" parent="ing" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;fontStyle=2;" value="Symbolication runs at ingest time, before hashing: stored exceptions are never re-symbolicated" vertex="1">
+ <mxGeometry height="25" width="620" x="250" y="215" as="geometry" />
+ </mxCell>
+ <mxCell id="ei1" edge="1" parent="ing" source="exc" target="pick" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ei2" edge="1" parent="ing" source="pick" target="match" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ei3" edge="1" parent="ing" source="match" target="resolved" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.15;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ei4" edge="1" parent="ing" source="resolved" target="ehash" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="ei5" edge="1" parent="ing" source="ehash" target="ins" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="elookup" edge="1" parent="1" source="match" target="cache" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.9;exitY=0;exitDx=0;exitDy=0;entryX=0.55;entryY=1;entryDx=0;entryDy=0;">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="elookupl" connectable="0" parent="elookup" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="artifact lookup" vertex="1">
+ <mxGeometry relative="1" x="0" y="0" as="geometry">
+ <mxPoint x="55" y="0" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/diagrams/symbolication-flows.png b/diagrams/symbolication-flows.png
new file mode 100644
index 00000000..ce338a13
Binary files /dev/null and b/diagrams/symbolication-flows.png differ
diff --git a/docs/pages/learn/build-tags.mdx b/docs/pages/learn/build-tags.mdx
index 0fd6e236..d6452d5d 100644
--- a/docs/pages/learn/build-tags.mdx
+++ b/docs/pages/learn/build-tags.mdx
@@ -2,6 +2,8 @@
The Traceway backend uses Go build tags to switch between storage backends and to embed the frontend. Storage is selected on two independent axes: the **telemetry** store (high-volume, append-only data) and the **transactional** store (relational/config data).
+<img src="/db-architecture.png" alt="Traceway database architecture: build-tag axes, main vs telemetry stores" style={{ maxWidth: '100%', height: 'auto' }} />
+
## Tags
### Telemetry axis
diff --git a/docs/pages/learn/data-flow.mdx b/docs/pages/learn/data-flow.mdx
index 451bbd63..d1101769 100644
--- a/docs/pages/learn/data-flow.mdx
+++ b/docs/pages/learn/data-flow.mdx
@@ -26,6 +26,12 @@ Here's how the concepts connect in a typical scheduled/async task:
3. **Batched and uploaded** β†’ All metrics are batched, compressed, and sent to Traceway with the next collection frame
4. **Displayed on dashboard** β†’ Metrics appear in configurable widget groups with line charts, area charts, bar charts, single values, and tables β€” filterable and groupable by tags
+## Ingestion pipelines
+
+On the server side all of this arrives through one of two paths: Traceway SDKs (frontend, mobile, and Go) post gzipped collection frames to `/api/report`, while OpenTelemetry-instrumented backends export OTLP to `/api/otel/v1/*`. Both authenticate with the project token, symbolicate stack traces at ingest, and land in the same telemetry store:
+
+<img src="/ingestion-flows.png" alt="Traceway ingestion pipelines" style={{ maxWidth: '100%', height: 'auto' }} />
+
## After the data collection
All this data flows to your Traceway dashboard where you can:
diff --git a/docs/pages/learn/index.mdx b/docs/pages/learn/index.mdx
index f0572ef3..1691381d 100644
--- a/docs/pages/learn/index.mdx
+++ b/docs/pages/learn/index.mdx
@@ -37,3 +37,9 @@ Endpoints, Tasks, and AI Traces all carry an `is_root` flag. A row is **non-root
<img src="/architecture.png" alt="Traceway Architecture" style={{ maxWidth: '100%', height: 'auto' }} />
See [Data Flow](/learn/data-flow) for how these connect during request processing, task execution, and metrics collection.
+
+## Authentication
+
+Every way in has its own credential: SDKs and OTel exporters use the project token, CI uses the source map token for symbol uploads, the dashboard uses a JWT or a personal access token, the [CLI](/learn/cli-auth) uses a device flow, and [MCP clients](/learn/mcp) use OAuth with PKCE. Role middleware scopes what an authenticated user can do.
+
+<img src="/auth-types.png" alt="Traceway authentication types" style={{ maxWidth: '100%', height: 'auto' }} />
diff --git a/docs/pages/symbolicator/index.mdx b/docs/pages/symbolicator/index.mdx
index 76afa6ef..18fd3109 100644
--- a/docs/pages/symbolicator/index.mdx
+++ b/docs/pages/symbolicator/index.mdx
@@ -8,6 +8,8 @@ The same engine runs three ways:
- **As an [OpenTelemetry Collector processor](/symbolicator/opentelemetry)**, so traces are rewritten before they reach any backend.
- **As an importable [Go library](/symbolicator/library)**, so you can call it from your own tooling.
+<img src="/symbolication-flows.png" alt="Symbolication flows: upload, matching, caching" style={{ maxWidth: '100%', height: 'auto' }} />
+
## When and where symbolication runs
Symbolication happens **once, at ingest**. A report arrives, each stack trace is resolved frame by frame, and the **resolved** trace is what gets hashed for grouping and stored. Nothing is re-resolved when you view an issue later.
diff --git a/docs/public/architecture.png b/docs/public/architecture.png
index 131eecd8..79cc3eaa 100644
Binary files a/docs/public/architecture.png and b/docs/public/architecture.png differ
diff --git a/docs/public/auth-types.png b/docs/public/auth-types.png
new file mode 100644
index 00000000..c5115750
Binary files /dev/null and b/docs/public/auth-types.png differ
diff --git a/docs/public/db-architecture.png b/docs/public/db-architecture.png
new file mode 100644
index 00000000..67ecceee
Binary files /dev/null and b/docs/public/db-architecture.png differ
diff --git a/docs/public/ingestion-flows.png b/docs/public/ingestion-flows.png
new file mode 100644
index 00000000..94c41355
Binary files /dev/null and b/docs/public/ingestion-flows.png differ
diff --git a/docs/public/symbolication-flows.png b/docs/public/symbolication-flows.png
new file mode 100644
index 00000000..ce338a13
Binary files /dev/null and b/docs/public/symbolication-flows.png differ