mariano/soleprint
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve soleprint docs: bilingual EN/ES, system pages, architecture cleanup

Browse Source
This commit is contained in:
buenosairesam
2026-01-27 09:15:59 -03:00
parent ed1c8f6c96
commit fa7bbe3953
6 changed files with 1366 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
docs/architecture/sidebar-injection.html Normal file
View File

@@ -0,0 +1,191 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Sidebar Injection - Soleprint</title>
<link rel="stylesheet" href="styles.css" />
<style>
pre {
background: #1a1a1a;
padding: 1rem;
border-radius: 8px;
overflow-x: auto;
font-size: 0.85rem;
line-height: 1.5;
}
code {
font-family: monospace;
background: #2a2a2a;
padding: 0.15rem 0.4rem;
border-radius: 4px;
}
pre code {
background: none;
padding: 0;
}
table {
width: 100%;
border-collapse: collapse;
margin: 1rem 0;
}
th, td {
border: 1px solid #3f3f3f;
padding: 0.5rem;
text-align: left;
}
th {
background: #1a1a1a;
}
</style>
<script src="../lang-toggle.js"></script>
</head>
<body>
<header>
<div id="lang-toggle"></div>
<h1>Sidebar Injection</h1>
<p class="subtitle">
<span class="lang-en">How managed room sidebar works</span>
<span class="lang-es">Como funciona el sidebar del managed room</span>
</p>
</header>
<main>
<section class="findings-section">
<h2>Overview</h2>
<p class="lang-en">The soleprint sidebar is injected into managed app pages using a hybrid nginx + JavaScript approach. This allows any frontend framework (React, Next.js, static HTML) to receive the sidebar without code modifications.</p>
<p class="lang-es">El sidebar de soleprint se inyecta en las paginas de apps manejadas usando un enfoque hibrido nginx + JavaScript. Esto permite que cualquier framework frontend (React, Next.js, HTML estatico) reciba el sidebar sin modificaciones de codigo.</p>
</section>
<section class="findings-section">
<h2>
<span class="lang-en">How It Works</span>
<span class="lang-es">Como Funciona</span>
</h2>
<pre>
┌─────────────────────────────────────────────────────────────────┐
│ Browser Request │
│ http://room.spr.local.ar/ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Nginx │
│ │
│ 1. Routes /spr/* → soleprint:PORT (sidebar assets + API) │
│ 2. Routes /* → frontend:PORT (app pages) │
│ 3. Injects CSS+JS into HTML responses via sub_filter │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Browser Renders │
│ │
│ 1. Page loads with injected CSS (sidebar styles ready) │
│ 2. sidebar.js executes (deferred, after DOM ready) │
│ 3. JS fetches /spr/api/sidebar/config │
│ 4. JS creates sidebar DOM elements and injects into page │
│ 5. Sidebar appears on left side, pushes content with margin │
└─────────────────────────────────────────────────────────────────┘</pre>
</section>
<section class="findings-section">
<h2>
<span class="lang-en">Key Design Decisions</span>
<span class="lang-es">Decisiones de Diseno Clave</span>
</h2>
<div class="findings-grid">
<article class="finding-card">
<h3><span class="lang-en">Why nginx sub_filter?</span><span class="lang-es">Por que nginx sub_filter?</span></h3>
<p class="lang-en"><strong>Framework agnostic</strong>: Works with any frontend. No app changes needed. Easy to disable.</p>
<p class="lang-es"><strong>Agnostico de framework</strong>: Funciona con cualquier frontend. Sin cambios en la app. Facil de deshabilitar.</p>
</article>
<article class="finding-card">
<h3><span class="lang-en">Why inject into &lt;/head&gt;?</span><span class="lang-es">Por que inyectar en &lt;/head&gt;?</span></h3>
<p class="lang-en">Next.js and streaming SSR may not include &lt;/body&gt; in initial response. &lt;/head&gt; is always present.</p>
<p class="lang-es">Next.js y SSR streaming pueden no incluir &lt;/body&gt; en la respuesta inicial. &lt;/head&gt; siempre esta presente.</p>
</article>
<article class="finding-card">
<h3><span class="lang-en">Why JS instead of iframe?</span><span class="lang-es">Por que JS en vez de iframe?</span></h3>
<p class="lang-en">No isolation issues, better UX (no double scrollbars), simpler CSS with margin-left.</p>
<p class="lang-es">Sin problemas de aislamiento, mejor UX (sin doble scrollbar), CSS mas simple con margin-left.</p>
</article>
</div>
</section>
<section class="findings-section">
<h2>
<span class="lang-en">Nginx Configuration</span>
<span class="lang-es">Configuracion de Nginx</span>
</h2>
<p class="lang-en">The nginx config injects CSS+JS into HTML responses:</p>
<p class="lang-es">La config de nginx inyecta CSS+JS en las respuestas HTML:</p>
<pre><code>location / {
proxy_pass http://frontend:PORT;
proxy_set_header Accept-Encoding ""; # Required for sub_filter
# Inject sidebar
sub_filter '&lt;/head&gt;'
'&lt;link rel="stylesheet" href="/spr/sidebar.css"&gt;
&lt;script src="/spr/sidebar.js" defer&gt;&lt;/script&gt;&lt;/head&gt;';
sub_filter_once off;
sub_filter_types text/html;
}</code></pre>
</section>
<section class="findings-section">
<h2>
<span class="lang-en">Port Allocation</span>
<span class="lang-es">Asignacion de Puertos</span>
</h2>
<p class="lang-en">Each room uses unique ports for concurrent operation:</p>
<p class="lang-es">Cada room usa puertos unicos para operacion concurrente:</p>
<table>
<tr><th>Room</th><th>Soleprint</th><th>Frontend</th><th>Backend</th></tr>
<tr><td>amar</td><td>12000</td><td>3000</td><td>8001</td></tr>
<tr><td>dlt</td><td>12010</td><td>3010</td><td>-</td></tr>
<tr><td>sample</td><td>12020</td><td>3020</td><td>8020</td></tr>
</table>
</section>
<section class="findings-section">
<h2>
<span class="lang-en">Sidebar Config API</span>
<span class="lang-es">API de Config del Sidebar</span>
</h2>
<p class="lang-en">The sidebar JS fetches configuration from <code>/spr/api/sidebar/config</code>:</p>
<p class="lang-es">El JS del sidebar obtiene configuracion de <code>/spr/api/sidebar/config</code>:</p>
<pre><code>{
"room": "amar",
"soleprint_base": "/spr",
"auth_enabled": true,
"tools": {
"artery": "/spr/artery",
"atlas": "/spr/atlas",
"station": "/spr/station"
}
}</code></pre>
</section>
<section class="findings-section">
<h2>Troubleshooting</h2>
<div class="findings-grid">
<article class="finding-card">
<h3><span class="lang-en">Sidebar not appearing</span><span class="lang-es">Sidebar no aparece</span></h3>
<p class="lang-en">Check if soleprint is running. Verify nginx has <code>Accept-Encoding ""</code>. Hard refresh (Ctrl+Shift+R).</p>
<p class="lang-es">Verificar que soleprint esta corriendo. Verificar que nginx tiene <code>Accept-Encoding ""</code>. Refresco forzado (Ctrl+Shift+R).</p>
</article>
<article class="finding-card">
<h3><span class="lang-en">sub_filter not working</span><span class="lang-es">sub_filter no funciona</span></h3>
<p class="lang-en">Ensure <code>proxy_set_header Accept-Encoding ""</code> is set. Check response is <code>text/html</code>.</p>
<p class="lang-es">Asegurar que <code>proxy_set_header Accept-Encoding ""</code> esta seteado. Verificar que la respuesta es <code>text/html</code>.</p>
</article>
</div>
</section>
</main>
<footer>
<p><a href="../"><span class="lang-en">← Back to index</span><span class="lang-es">← Volver al indice</span></a></p>
</footer>
</body>
</html>