Alex OS is the reasoning layer that turns the site into a connected operating system.
It sits between the CMS, the public website, and the admin workflows. The CMS stays the source of truth; Alex OS reads the schema and content, interprets it through configurable reasoning profiles, and returns structured UI, recommendations, answers, and actions.
Alexandra NacSenior Full-Stack Developer | Applied AI Developer | AI Workflows · RAG Systems · Agentic Applications
System definition
Alex OS is a personal operating layer for this website: a reasoning engine that understands the content model, the visitor context, the admin workflow, and the relationships between published work. It is built as a separate FastAPI service beside the Next.js CMS, not as a single prompt or a cosmetic chat widget.
The core idea is simple but powerful: the site should not be a pile of disconnected pages. Every page, note, build, proof item, experiment, signal, contact route, and future custom type becomes part of a structured system. Alex OS reads that structure, reasons over it, and helps the visitor or owner choose the next useful path.
- Next.js public site
- CMS registry
- Alex OS FastAPI
- structured blocks + actions
It is not just a chatbot.
The assistant is one interface into the system, but Alex OS also powers journey selection, related-content recommendations, page-aware actions, admin suggestions, score refreshes, workflow orchestration, and eval runs.
It treats content as a graph.
Pages, builds, proof, notes, signals, experiments, and future custom types become typed nodes with fields, metadata, relationships, and weights. The system can then connect evidence, work, ideas, and next actions.
It is enhancement-only.
If the FastAPI service is offline, the website still loads. The CMS client returns null on Alex OS failures, public sections hide gracefully, and the core site remains usable.
It is review-first.
Generated work follows a controlled state path: generated, needs review, approved or rejected, then applied. Alex OS can recommend and draft, but important changes still route through owner review.
Interface layer
The public Next.js site and the admin CMS are the surfaces. They render the experience, store content, collect privacy-light interaction signals, and call Alex OS only through server-side API routes.
Content registry
Every post type, field, permalink, visibility flag, reasoning profile, and Alex OS exposure rule lives in CMS data. Alex OS reads this registry instead of assuming fixed models like Project, Proof, or Thinking.
Reasoning service
The separate FastAPI service on 127.0.0.1:8010 validates inputs with Pydantic, normalizes content into generic ContentNode records, resolves profiles/personas, and composes structured blocks.
Config bundle
Behavior is driven by CMS-managed OS configuration: reasoning profiles, prompt templates, block types, personas, actions, model routes, guardrails, retrieval settings, budgets, and feature flags.
Output contract
The frontend does not receive arbitrary model prose as UI. It receives typed JSON blocks and actions such as summary cards, technical breakdowns, recommendation cards, process cards, and CTA cards.
Learning loop
Impressions, accepted suggestions, dismissed suggestions, content scores, eval cases, generated outputs, relationships, and guide memory give Alex OS feedback about what is useful without exposing raw database access.
A schema-driven pipeline moves from content registry to safe, reviewable intelligence.
The system is designed so new content types can be added without rewriting the reasoning layer. Alex OS discovers structure, normalizes content, retrieves context, resolves intent, composes blocks, and feeds decisions back into analytics and learning loops.
1. Schema discovery
The CMS exposes internal registry endpoints for content types, fields, settings, public visibility, Alex OS visibility, permalink rules, and reasoning profiles. Alex OS reads that registry through an authenticated internal HTTP client.
content_types + content_type_fields -> /api/internal/*2. Content normalization
Raw CMS rows are converted into generic ContentNode objects. The normalized shape includes id, type, slug, title, status, fields, relationships, and metadata, so the reasoning layer can handle new content types without new backend models.
CMS item -> ContentNode{id,type,slug,title,fields,relationships}3. Retrieval and context assembly
When a visitor asks a question or a page requests recommendations, Alex OS builds a scoped context from content nodes, field weights, relationships, current page data, journey mode, and retrieval services. Semantic retrieval can be used when configured; keyword fallback keeps the system available.
page + query + journey_mode + graph signals -> ranked context4. Persona and journey resolution
The selected thread and session signals influence what the system prioritizes: what I've shipped lifts systems and outcomes, where I've worked lifts roles and ownership, and what I know lifts architecture notes and reasoning.
persona_resolver + journey weights -> intent profile5. Prompt and model routing
For LLM-backed paths, prompt templates come from the OS config bundle and are rendered with bounded context. Model routing and budgets decide which model can be used, while deterministic generators cover safe fallback paths.
prompt_template + model_route + budget -> answer plan6. Block composition
The block composer translates reasoning into frontend-safe UI blocks. Blocks are schema-checked against the block registry before they reach the public site, which keeps rendering predictable and prevents malformed model output from becoming UI.
reasoning result -> UIBlock[] + AlexAction[]7. Action execution boundary
Actions are routed through a hardcoded allowlist of safe executors. Public actions run through Next.js proxy routes, admin actions create reviewable diffs or suggestions, and nothing gives the model direct database write access.
action_id -> allowed executor -> reviewable result8. Feedback, evals, and memory
Every useful signal can be logged: block impressions, assistant questions, LLM traces, accepted suggestions, rejected suggestions, score changes, eval pass rates, and synthesized learnings. Those signals tune future recommendations and expose what Alex OS has learned.
events + traces + evals + guide_memory -> next iteration