Sol37 Site Audit

This is the committed audit summary for the Sol-37 site as inspected on 2026-04-16. It is intended to match the current in-tree operator…

Executive Summary

This is the committed audit summary for the Sol-37 site as inspected on 2026-04-16. It is intended to match the current in-tree operator documentation in www/README.md and the browser manual in www/site-server.html. Sol-37 Site Audit Date: 2026-04-17 Repo: /home/david/random Site root: /home/david/random/www Primary host: sol.system42.one Local origin: http://127.0.0.1:8888 Scope This is the committed audit summary for the Sol-37 site as inspected on 2026-04-16.

Sol-37 Site Audit

Date: 2026-04-17
Repo: /home/david/random
Site root: /home/david/random/www
Primary host: sol.system42.one
Local origin: http://127.0.0.1:8888

Scope

This is the committed audit summary for the Sol-37 site as inspected on 2026-04-16. It is intended to match the current in-tree operator documentation in www/README.md and the browser manual in www/site-server.html.

The key point remains unchanged:

Current Public Shape

Primary public surfaces:

- /
main shell
- /gui
direct shell deep-link entry
- /chat
dedicated public Sol console
- /dashboard
public AI dashboard app
- /sitemap.html
archive browser
- /site-metrics.html
traffic monitor
- /programs/logbook.html
public logbook
- /programs/media-player.html
media surface

Primary API routes:

The local site origin is still Caddy on 127.0.0.1:8888.

Frontend Architecture

Shell

www/index.html is the primary shell and still acts as a single-file window manager:

  • desktop icons
  • Start menu
  • taskbar/task buttons
  • draggable windows
  • iframe-backed content/program surfaces
  • shareable /gui?i=... links
  • built-in floating Sol assistant orb

The shell is coherent, but the tradeoff remains obvious: the central interaction model is easy to deploy and hard to modularize.

Dedicated Chat

www/chat/ is now a first-class client rather than a placeholder.

Important current behavior:

  • same-origin /api/chat
  • streamed text over SSE
  • streamed or cached voice playback through /api/chat/speak
  • orb presence card aligned with the desktop assistant
  • client-side diagnostics for transport/latency/cache state

Dashboard App

www/dashboard/ is now a first-class surface published from the main desktop shell.

Current behavior:

Assistant Surfaces

There are two real assistant clients:

  1. floating desktop assistant in index.html
  2. dedicated /chat client in www/chat/

Both now share the same broad runtime model:

  • persistent session id
  • same-origin chat backend
  • streamed chat deltas where streaming is appropriate
  • optional voice playback
  • retrieval grounding
  • same-origin routes

Assistant And Voice Stack

Chat Flow

Current request flow:

  1. Browser sends POST /api/chat
  2. Caddy proxies to sol_chat_api.py
  3. sol_chat_api.py:
  4. updates session history
  5. fetches retrieval context from the knowledge API
  6. builds grounded prompt state
  7. queries the local model backend on 127.0.0.1:18080
  8. The transport shape depends on client and context:
  9. /chat uses SSE events:
  10. status
  11. delta
  12. done
  13. error
  14. the floating desktop assistant now prefers one-shot JSON for page-grounded turns and keeps SSE for non-page/freeform turns
  15. The desktop assistant retries without stream if a streamed turn faults or produces no usable text
  16. Browser updates the visible transcript either incrementally or from the final JSON payload

Desktop Assistant Context Behavior

The desktop assistant supports two separate context strategies:

  • compact page context for prompt grounding
  • full extracted page text for read-aloud behavior

This separation is important and now explicit in the codebase. Using the same bounded context for narration caused incomplete read-aloud behavior.

The compact prompt context is now deliberately smaller than before, and the desktop assistant fingerprints page state from the target, title, content type, headings, and bounded content. That fingerprint is used for client-side caching of:

  • grounded page replies
  • generated read-aloud narration text

Repeated page questions now reuse the cached reply until the page content changes. Repeated read-aloud requests reuse the cached narration text until the page content changes.

Voice Flow

Current low-latency voice flow:

  1. Browser identifies a speakable chunk
  2. Browser points its <audio> element at GET /api/chat/speak?text=...
  3. API either:
  4. streams cached MP3 bytes from disk, or
  5. streams fresh ElevenLabs output via 11speak.py
  6. Browser starts playback before the whole audio file is finished

This is the significant current improvement over the older blob-based path.

Current Voice Caching

Speech cache location:

  • ~/.local/share/sol_chat_web/tts_cache

Behavior:

  • repeated identical text reuses cached MP3 by content hash
  • uncached text still streams while being generated
  • streamed chat replies can start speaking from completed sentence chunks before the full reply finishes
  • when the browser reuses cached narration text, the server-side TTS cache also reuses the previously generated MP3

Practical result:

  • earlier first audio
  • less “dead air” after the model begins replying
  • no need to wait for full MP3 materialization before browser playback

Desktop Playback Controls

The floating assistant now has a real transport model instead of a fire-and-forget orb:

  • explicit Play / Pause / Resume button labeling based on current playback state
  • hard stop/reset when the assistant is closed
  • queued speech will not resume after close
  • orb click now toggles or resumes playback instead of blindly restarting speech

Prompt Suggestions

The floating assistant still exposes three quick prompts, but they no longer behave like three static presets:

  • the first suggestion stays anchored
  • the second and third are rerolled from a broader prompt pool each time the popup opens
  • page-grounded prompt pools are generated from the current page title, headings, and content

HTTP And Proxy Topology

Current Caddy behavior from bin/Caddyfile.pkd_share:

Current caching semantics:

  • chat assets intentionally non-cacheable
  • audio assets long-lived/immutable
  • images/video/static assets short-lived public cache
  • streamed voice route explicitly no-store

Backend Services

Observed relevant user services:

  • caddy-sol37.service
  • sol-chat-api.service
  • sol-chat-model.service
  • local-dashboard-api.service
  • dashboard-access-daemon.service
  • knowledge-query-api.service
  • sol37-gui-share.service
  • site-index-watch.service
  • video-playlist-watch.service
  • audio-playlist-watch.service
  • public-logbook-api.service
  • public-logbook-irc-logger.service

Observed relevant timers:

  • site-metrics-snapshot.timer
  • synthetic-logbook-snapshot.timer

Observed system service dependency:

  • ngircd.service

Boot persistence:

  • Linger=yes for user david

That remains operationally critical. Without linger, the site stack is only a logged-in desktop illusion.

Generated State

Generated artifacts with operational significance:

These are not incidental build outputs. They materially affect browser-visible behavior.

Current Strengths

Current Risks

Verification Commands

Current useful checks:

bash
git -C /home/david/random status --short
curl -I -s http://127.0.0.1:8888/
curl -s http://127.0.0.1:8895/api/chat/health
curl -s http://127.0.0.1:8896/api/dashboard/status
curl -s http://127.0.0.1:8897/api/dashboard-access/status
curl -sD - -o /tmp/test.mp3 'http://127.0.0.1:8895/api/chat/speak?text=hello&session=test'
file /tmp/test.mp3
curl -s http://127.0.0.1:8892/health | jq
curl -s 'http://127.0.0.1:8890/messages?channel=public-logbook&limit=3'
systemctl --user --type=service --state=running | rg -i 'caddy|sol-chat|knowledge|logbook|site|video|audio|sol37'
systemctl --user list-timers --all | rg 'site-metrics|synthetic'
ss -ltnp | rg '(:8888|:8890|:8892|:8893|:8895|:8896|:8897|:18080)'
python3 /home/david/random/bin/check_sol_chat_asset_versioning.py

Audit Conclusion

Sol-37 is still best understood as a hybrid archive system:

The most important delta since the earlier audit is the maturity of the assistant/chat runtime. The assistant is no longer a passive shell flourish. It is now a genuine multi-surface client with:

That change needed documentation. This audit now treats it as first-order architecture rather than a small UI feature.