# Blueprint Nexus (Blueprint Society) — Comprehensive Product & Technical Documentation

> Blueprint Nexus is a living intelligence workspace and connected second brain that unifies notes, ideas, roadmaps, and software architectures into an interactive 2D/3D knowledge graph — the Blueprint Knowledge Network (BKN). Powered by multi-model AI reasoning (Flash & Pro + BYOK) and a governed agent kernel, Nexus scales from individual personal knowledge management up to enterprise-grade AI coding fleets.

---

## 1. Positioning

### Who this is for

Nexus is built for anyone who thinks, plans, and creates in an era of rapid information and AI acceleration:
- **Solo Thinkers, Researchers & Writers**: Individuals needing a visual "second brain" to interconnect literature notes, research citations, and ideas in 2D/3D space with zero-plugin cloud sync.
- **Founders & Creators**: Solo entrepreneurs and product creators coordinating GTM roadmaps, marketing launches, moodboards, and customer personas.
- **Cross-Functional Teams & PMs**: Teams uniting real-time collaborative Markdown specs, agile Kanban task boards, and Google Calendar milestones into a single hub.
- **Platform Leads & Engineers**: Technical teams mapping microservice dependencies, architectural decisions, and running autonomous AI coding agents under strict two-pass verification gates.

### The problem

Information and action are fundamentally siloed across disparate tools. Notes sit buried in nested folder trees, tasks get stranded in disconnected issue lists, and strategic decisions disappear in fleeting chat threads. For teams adopting AI agents, autonomous models generate changes without knowing the historical context, downstream dependencies, or load-bearing invariants.

### The approach

Move scattered thoughts, documents, and technical specs into a structured, bidirectional knowledge graph (BKN) that humans and AI copilots navigate in real time. Combine visual 2D/3D mind mapping with outcome-driven project planning and a governed two-pass execution kernel that turns ideas into verified execution.

---

## 2. System Architecture & Core Modules

Turborepo monorepo with strict package boundaries:

- **apps/web**: Next.js 16 (React 19) App Router application — 2D/3D BKN visualizer, collaborative document editor, live agent monitor, workspace dashboards, billing.
- **apps/mobile**: Expo Go and Capacitor iOS client sharing the web and shared packages.
- **packages/agent-fleet**: Framework-agnostic TypeScript runtime powering agent execution loops (`runTick`), memory buffers, tool dispatchers, and risk-gated execution policies.
- **packages/kernel**: Governed agent kernel containing security constraints, identity rules, and immutable audit logs.
- **packages/mcp-server**: Model Context Protocol server exposing the BKN and workspace operations as agent tools.
- **packages/shared**: Shared domain models (`BknNode`, `BknEdge`, `AgentTask`, `Proposal`, `TelemetryLog`), schema types, and Supabase client helpers.
- **supabase/migrations**: PostgreSQL schema, recursive CTE graph queries, Row-Level Security policies, and event triggers.

---

## 3. Blueprint Knowledge Network (BKN)

A unified graph where every node is an organizational or technical artifact and every edge is a semantic dependency or operational relationship.

### Core node types

- `initiative`: Strategic objectives and roadmap items.
- `service`: Microservices, backend APIs, and third-party integrations.
- `component`: Frontend modules, design systems, and client libraries.
- `protocol`: Standard operating procedures, governance rules, deployment policies.
- `spec`: Interface definitions, API schemas, RFC documents.
- `agent`: Registered autonomous agents with execution privileges.

### Core edge types

- `depends_on`: Direct technical or operational dependency.
- `implements`: A component or service realizing a spec or initiative.
- `governs`: A protocol or policy regulating an agent, service, or workflow.
- `triggers`: Event-driven execution relationship.
- `monitors`: Telemetry, health check, or drift observation channel.

### Continuous ingest and provisional state

Webhook consumers keep the graph current from GitHub (commits, pull requests) and Linear (issue transitions), alongside specs and documents authored directly in Nexus.

Anything the system infers rather than observes enters the graph as **provisional** (`is_provisional = true`, rendered with a pulsing dashed outline) and remains provisional until a human confirms it. This is deliberate: a context layer that silently asserts unverified relationships is worse than no context layer, because agents will act on it.

### Graph engine implementation

The BKN is stored in ordinary PostgreSQL tables on Supabase and traversed with recursive Common Table Expressions:

- **Downstream impact queries**: identify every service, spec, and team affected by an upstream change.
- **Upstream root-cause tracing**: identify which initiatives and requirements define a given component.
- **Cycle detection**: prevent circular operational or software dependencies.
- **Performance**: multi-hop recursive path queries return in low single-digit milliseconds at current graph sizes.

Choosing recursive CTEs over a dedicated graph database removes a second datastore from the operational surface and keeps graph reads inside the same transactional boundary as application data. This is an implementation decision, not a product feature.

---

## 3.1 Modular Sidebar Engine & Workspace Personalization

Blueprint Nexus treats user navigation as a fully declared, dynamic, and user-governed schema rather than hardcoded UI chrome. The sidebar is structured around a composable document model (`SidebarDocument`, `SidebarDesignConfig`, and `SidebarChromeConfig`).

### Structural Design Archetypes

1. **Workspace Stack (`productivity` / `workspace`)**:
   - Multi-tab productivity shell equipped with quick-action toolbars, reorderable workspace tabs, and resizable collapsible section drawers.
   - Designed for cross-functional teams balancing documents, tasks, 2D/3D graphs, and calendar scheduling.
   - Typography: Plus Jakarta Sans with distinct section headers and action triggers.

2. **IDE Activity Rail (`ide`)**:
   - Developer-centric 48px slim icon rail on the left accompanied by a full-height flush navigation tree panel.
   - Monospace JetBrains Mono font formatting, high-density line heights, and keyboard-first navigation shortcuts.
   - Ideal for software engineers, platform architects, and terminal/code-heavy workflows.

3. **Journal Continuous Stream (`journal`)**:
   - Streamlined, tab-less vertical stream grouping notes, thoughts, and tasks chronologically by date.
   - Fluid Outfit Sans typography with zero dividers, designed for daily reflections, meeting capture, and quick idea logging.

### 4-Tier Layout Density Ladder

- **Compact** (26px row height, 13px icon, 11px font): Maximizes vertical data density; ideal for expansive information architectures and power users.
- **Standard** (30px row height, 14px icon, 12px font): Balanced default desktop ergonomics and spacing.
- **Comfortable** (36px row height, 16px icon, 13.5px font): Increased padding and larger touch targets for high-legibility readability.
- **Expansive** (42px row height, 18px icon, 15px font): Spacious touch targets and presentation-ready scale.

### Visual Chrome & Granular Customization

- **Chrome Toggles**: Independently show/hide section glyphs, item badges (status/priority pills), and metadata/timestamps.
- **Icon Rendering Styles**: Toggle between crisp outline glyphs and solid filled shape icons.
- **Custom Workspace Tabs**: Create bespoke tabs (e.g., Sprint Backlog, Q3 Launch, Client Alpha) and reorder navigation sections via drag-and-drop.
- **AI-Powered Sidebar Architect (`SidebarDesignAIChat`)**: Natural language conversational assistant enabling users to describe desired navigation changes (e.g., "Show an IDE rail with docs, tasks, and agents on top") and execute schema updates with a single click.

---

## 4. Governed Agent Fleet & Two-Pass Execution

Agents never mutate on first contact. Every action splits into two phases.

### Pass A: Research, architecture, and proposal (read-only)

- The agent explores the BKN, codebase, and issue trackers using read-only tools.
- Mutating operations are unavailable, not merely discouraged.
- The agent emits a structured Proposal: affected file paths, type contracts, and a step-by-step implementation plan.

### Pass B: Gated implementation and verification

- Entered only after a human reviewer or an explicit policy approves the Proposal.
- Modifications execute transactionally with rollback.
- Automated verification runs immediately: type-checking, linting, unit tests.
- Every tool invocation, prompt, response, and approval event is committed to an append-only audit log.

### 4-tier risk gating

- **Tier 0 (Informational)**: read-only inspection, search, graph querying. Auto-approved.
- **Tier 1 (Low)**: formatting, documentation, non-breaking draft proposals. Auto-approved with logging.
- **Tier 2 (Medium)**: code changes on isolated feature branches or non-critical configuration. Requires peer review or passing automated validation.
- **Tier 3 (High/Critical)**: schema migrations, infrastructure alterations, billing changes. Requires multi-party manual sign-off.

### Autonomy levels

Independently of tier, each agent runs at a declared autonomy level capping which tiers it may reach:

- **L0**: proposal only, no execution under any circumstances.
- **L1 (Supervised)**: read tools permitted; all modifications, including low-risk memory writes, require manual review.
- **L2 (Coordinated)**: Tier 0–1 tools proceed automatically; Tier 2–3 writes remain gated.
- **L3**: broadest autonomy, still bounded by Tier 3 sign-off requirements.

---

## 5. Competitive Positioning

| Dimension | Blueprint Nexus | Linear / Jira | LangChain / AutoGPT / CrewAI | Assistant built-in memory |
| :--- | :--- | :--- | :--- | :--- |
| **Data representation** | Unified graph linking tasks, code, specs, decisions, and agents | Flat rows and disconnected tickets | Unstructured buffers or vector chunks | Per-developer conversational recall |
| **Workspace & sidebar flexibility** | 3 design archetypes (Stack, 48px IDE rail, Journal stream), 4-tier density ladder, AI layout designer | Fixed left rail with immutable list structure | CLI / headless runtime only | Fixed side-panel with no archetype support |
| **Agent governance** | Two-pass kernel: read-only proposal, then gated execution | None | Optimistic execution loops | Vendor-defined, not team-configurable |
| **Impact analysis** | Recursive CTE traversal before a change lands | Manual cross-referencing | None | None |
| **Scope** | Organization-wide, cross-tool | Single tracker | Single application | Single tool, single user |
| **Drift detection** | Automated alerts on divergence between commits and recorded intent | None | None | None |
| **Auditability** | Append-only log of every tool call, prompt, and approval | Ticket history only | Application-defined | Opaque |

The durable distinction against assistant-native memory is scope and incentive: the BKN spans repositories, trackers, chat, and people rather than one tool and one user, and a vendor shipping its own coding agent has a structural conflict of interest in building the layer that constrains it.

---

## 6. Primary Use Cases

1. **Customized developer workspace**: a software engineer switches their navigation shell to an IDE rail with 48px icons and monospace tree items, keeping specs and agent consoles in tight reach.
2. **Agent change review**: an agent proposes a refactor; the graph surfaces the four downstream consumers and the decision record explaining the invariant it was about to break.
3. **Decision recall**: when a change proposes reversing an earlier architectural choice, the original reasoning and its author surface automatically.
4. **Pre-deploy impact tracing**: run a recursive dependency trace before shipping a breaking API change.
5. **Drift control**: detect divergence between what was specified and what was implemented, continuously rather than at review time.
6. **Governed automation**: allow agents to perform routine refactors and maintenance without risking unapproved production changes.
7. **Audit and compliance**: maintain immutable, timestamped records of every model invocation and human approval for review.
8. **Multi-team scoping**: role-based isolation across teams with executive visibility across the whole graph.

---

## 7. Security & Tenancy

- PostgreSQL Row-Level Security on every table, tied to authenticated user and workspace IDs via `auth.uid()`.
- Role-based access control at workspace and section granularity.
- Ephemeral, isolated sandbox environments for agent code execution.
- Append-only audit logging of tool invocations, prompts, responses, and approval events.
- No model training on customer data.
- Bring-your-own-key support so model traffic can run under the customer's own provider account.

---

## 8. Pricing & Membership Tiers

- **Free Tier ($0.00)**: 1 Workspace & 1 Solo Seat, 4 Custom Sidebar Sections, 10 App Integrations, 100 Monthly Workflow Actions, 50 BKN Graph Nodes, 500 MB Encrypted Storage, 7-Day History. BYOK Support (OpenAI, Gemini, Anthropic).
- **Hobby Tier ($4.99/month)**: Standard Monthly AI Credits (1.0M), 3 Workspaces & 1 Solo Seat, 8 Custom Sidebar Sections, 25 App Integrations, 1,000 Monthly Actions, Model Context Protocol (MCP) Access, 10 Mins/mo Sandbox VM Compute, 250 Graph Nodes, 100 Web Research Crawls/mo, 5 GB Storage & 30-Day History.
- **Pro Member ($19.99/month)**: 10× Monthly AI Credits (10.0M), 10 Workspaces & 25 Team Seats, 20 Custom Sidebar Sections, 50 App Integrations, 10,000 Monthly Actions, Advanced Multi-Server MCP Orchestration, 1 Hour/mo Sandbox VM Compute, 5,000 Graph Nodes, 500 Web Research Crawls/mo, 25 GB Storage & 90-Day History.
- **Ultra Studio ($99.99/month)**: 50× Monthly AI Credits (50.0M), 25 Workspaces & 100 Team Seats, Unlimited Custom Sidebar Sections, 100 App Integrations, 50,000 Monthly Actions, Enterprise Hosted MCP, 10 Hours/mo Sandbox VM Compute, 25,000 Graph Nodes, 2,500 Web Research Crawls/mo, 100 GB Storage & 365-Day History.
- **Enterprise Vetted (Custom Pricing + Grants)**: Custom multi-agent fleets, capital grant eligibility, custom orchestration runtime support, dedicated cloud GPU sandboxes, tailored SLAs, and on-premise deployments.

---

## 9. Frequently Asked Questions

### How customizable is the Blueprint Nexus sidebar and workspace?

Every aspect of the Blueprint Nexus sidebar and workspace is fully customizable. You can choose between three distinct layout archetypes (Workspace Stack, IDE Activity Rail, and Journal Stream), toggle between four layout density modes (Compact, Standard, Comfortable, Expansive), create custom workspace tabs for active sprints or clients, drag and reorder navigation sections, customize visual chrome badges and icon styles, and use the AI Sidebar Architect to redesign your navigation via natural language chat.

### What are the three sidebar design archetypes in Blueprint Nexus?

1. **Workspace Stack**: The default multi-tab layout equipped with a quick-actions toolbar, reorderable tabs, and resizable collapsible section drawers.
2. **IDE Rail**: A developer-focused 48px slim activity rail with a full-height flush navigation tree and monospace JetBrains Mono typography.
3. **Journal Stream**: A date-grouped continuous vertical stream for chronological notes, daily logs, and freeform writing without tabs or dividers.

### What layout density modes are available?

Blueprint Nexus supports four layout density modes:
- **Compact** (26px row height, 13px icon, 11px font): High-density display for power users.
- **Standard** (30px row height, 14px icon, 12px font): Balanced default desktop ergonomics.
- **Comfortable** (36px row height, 16px icon, 13.5px font): Relaxed touch targets and visual breathing room.
- **Expansive** (42px row height, 18px icon, 15px font): Large typography and generous spacing for presentations and touch screens.

### What is Blueprint Nexus?

A memory and governance layer for engineering teams running AI coding agents. It maintains a live graph of architecture, dependencies, and decisions, and requires agents to plan against that graph and clear human approval before making changes.

### Who is it for?

Software teams of roughly 20–100 people that have adopted AI coding agents heavily and can no longer verify the volume of change those agents produce. The typical buyer is a head of platform, staff engineer, or VP of engineering. It is also used by solo thinkers, researchers, founders, and creators as a visual second brain.

### How does the governed fleet prevent unintended changes?

A 4-tier risk classifier combined with the two-pass kernel. Agents submit a read-only proposal in Pass A and must obtain the approval their risk tier requires before Pass B executes with verification and rollback.

### Where does the graph's information come from?

Continuous webhook ingest from GitHub commits and pull requests and Linear issue transitions, plus specs and documents authored in Nexus. Inferred relationships enter as provisional and require human confirmation.

### What database technologies power the graph?

Supabase and PostgreSQL using native recursive Common Table Expressions, giving multi-hop dependency tracing in low single-digit milliseconds without a proprietary graph database.

### What models and integrations does Nexus support?

Multiple model providers with bring-your-own-key across Anthropic, OpenAI, Google, Groq, DeepSeek, Mistral, and local Ollama, bound through Model Context Protocol servers, plus a connector catalog including GitHub, Linear, Slack, Google Drive, Notion, and Figma.

### How is tenant data protected?

PostgreSQL Row-Level Security tied to authenticated user and workspace IDs, role-based access control, ephemeral sandboxes, append-only audit logs, and no model training on customer data.

### How is this different from the memory built into my coding assistant?

Assistant memory is scoped to one tool and one developer. The BKN is organization-level and cross-tool, spanning repositories, trackers, chat, and people, and it governs agent execution rather than merely informing it.

---

## 10. Official Navigation URLs

- Platform Home: https://bluesc.org/
- Features & Capabilities: https://bluesc.org/features
- Pricing & Plans: https://bluesc.org/pricing
- Documentation & Guides: https://bluesc.org/help
- Membership & Enterprise: https://bluesc.org/join
- Application Portal: https://bluesc.org/apply
- Privacy Policy: https://bluesc.org/privacy
- Terms of Service: https://bluesc.org/terms
- Standard LLM Summary: https://bluesc.org/llms.txt
- Full LLM Context: https://bluesc.org/llms-full.txt