Improve soleprint docs: bilingual EN/ES, system pages, architecture cleanup
This commit is contained in:
buenosairesam
191
docs/architecture/sidebar-injection.html
Normal file
191
docs/architecture/sidebar-injection.html
Normal 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 </head>?</span><span class="lang-es">Por que inyectar en </head>?</span></h3>
|
||||
<p class="lang-en">Next.js and streaming SSR may not include </body> in initial response. </head> is always present.</p>
|
||||
<p class="lang-es">Next.js y SSR streaming pueden no incluir </body> en la respuesta inicial. </head> 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 '</head>'
|
||||
'<link rel="stylesheet" href="/spr/sidebar.css">
|
||||
<script src="/spr/sidebar.js" defer></script></head>';
|
||||
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>
|
||||
Reference in New Issue
Block a user