Architecture

The P31 stack is a sovereign, local-first AI infrastructure for neurodivergent families.

High-Level Overview

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ p31 CLI │────▶│ p31-router │────▶│ DeepSeek │
│ (TUI) │ │ :4001 │ │ (OpenAI │
│ MCP agent │ │ (proxy) │ │ compatible) │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ phos-forge │ │ google- │
│ (MCP stdio) │ │ workspace │
│ 26 tools │ │ (MCP stdio) │
└──────────────┘ └──────────────┘

Components

p31 CLI (Go)

Cobra + Viper for command line and config

Bubble Tea + Lipgloss for the TUI

MCP client via mark3labs/mcp-go

OpenAI client via sashabaranov/go-openai

28+ commands, 60s request timeout, clean MCP shutdown

p31-router (Python)

Lightweight OpenAI-compatible proxy on port 4001

Three tiers: scavenger (Gemini free), flash (DeepSeek Chat), premium (DeepSeek Reasoner)

Sequential fallback: premium → flash → scavenger → error

Token bucket rate limiting (60 events/min)

PHOS Forge MCP (Node.js)

26 tools: file classification, cognitive state, deploy, logbook, brain-dump, jitterbug, etc.

Line-by-line JSON-RPC over stdio

Self-healer, Reflex Arc, Tide, Kappa, Cartographer subsystems

Google Workspace MCP (Node.js)

Calendar, Gmail, Drive, Docs, Sheets, Contacts

OAuth 2.0 with local token storage

Multi-account support

Data Flow

User types a message in p31 chat

Go CLI sends OpenAI-format request to localhost:4001/v1

Router proxy forwards to DeepSeek (or falls back)

If the AI requests a tool, the CLI executes the tool via MCP stdio

Tool results are fed back to the AI for a final answer

Response is displayed in the TUI