Project Structure

pinky-and-the-brain/
  docs/                               # Docusaurus documentation website (this site)
  terraform/                          # AWS Cloud IaC configuration
    main.tf                           # ECR, Lightsail container service + deployment, CloudFront
    variables.tf                      # Deployment settings & regional variables
    outputs.tf                        # AWS service endpoints (Lightsail/CloudFront/ECR)
    aws-permissions.json              # Single IAM policy covering the create, report and cleanup/teardown scripts
  src/
    index.ts                          # Raw ACP stdin/stdout entrypoint
    cli.ts                            # Standalone interactive REPL CLI
    server.ts                         # Express REST API (HTTP, SSE streaming, Slack/Teams webhooks)
    mcp.ts                            # Model Context Protocol (MCP) server
    graph-sdk.ts                      # SDK exports for modular reuse of the graph engine
    config.ts                         # Configuration parser & Zod schema validator
    agents/                           # The Brain (deep agent)
      types.ts                        # Run state, progress & BrainAgent interface
      agent.ts                        # createDeepAgent assembly (model + tools + prompt)
      graph.ts                        # runGraphWorkflow compatibility layer
      persona.ts                      # The Brain's voice & catchphrases
      prompts.ts                      # Writing standard, journey state machine & teaching loop
      layout.ts                       # Article layout marks → the blog's MDX (pure transforms)
      tools.ts                        # Topics, subtopics, retrieval, article files
      artifacts.ts                    # Records tool-written files as downloadable artifacts (remote delivery mode)
    protocol/                         # ACP JSON-RPC standard parsing
      acp-server.ts                   # ACP protocol handler
      messages.ts                     # Validation schemas (Zod)
    storage/                          # State persistence
      sqlite.ts                       # SQLiteCheckpointer extending LangGraph's BaseCheckpointSaver
      s3.ts                           # S3 storage client wrapper (with offline local fallback)
      knowledge-store.json            # Pre-compiled chunks: id, content, area, source, heading
      embeddings.bin                  # One quantised 256d vector per chunk (optional)
    scripts/
      ingest.ts                       # Rebuilds the local vector store from source documents
    utils/                            # Shared utilities
      logger.ts                       # Centralized console and file logger (agent.log & stderr)
      messages.ts                     # LangChain message helper functions
      model.ts                        # LLM factory (Anthropic Claude only)
      retrieval.ts                    # Tokenising, stemming, BM25, rank fusion (pure)
      embeddings.ts                   # Gemini vectors: quantise, cosine, binary store
      blog-mcp.ts                     # Client session against the blog's `articles` MCP server
      image-gen.ts                    # Cover & figure generation (soft-failing)
      illustration-styles.ts          # The style catalogue and the per-article pick
      session.ts                      # Stable thread ids for MCP callers
    tests/
      unit/                           # Vitest unit tests
      integration/                    # Vitest integration tests
  scripts/                            # Deploy & operations scripts
    deploy.js                         # Deploy orchestration script (Docker build, ECR push, Terraform run)
    report-infra.ps1                  # PowerShell script for AWS infrastructure status audits
    create-infra.ps1                  # PowerShell script provisioning the full AWS stack from nothing
    cleanup-infra.ps1                 # PowerShell script deleting AWS resources - non-project, or all with -IncludeProject (dry run by default)
    tail-logs.js                      # Script to stream cloud container logs
    test-tracing.js                   # Script to verify LangSmith tracing connection
  Dockerfile                          # Multi-stage container build
  langgraph.json                      # LangGraph Studio / CLI project config
  package.json                        # Scripts & dependencies
  tsconfig.json                       # TS compilation config
  vitest.config.ts                    # Test runner config

Module boundaries

• Entrypoints (src/index.ts, cli.ts, server.ts, mcp.ts) each validate configuration on startup, then delegate all actual work to runGraphWorkflow() from src/agents/graph.ts. They differ only in transport (stdio JSON-RPC, terminal REPL, HTTP/SSE, MCP stdio) and in how they format the final response.
• agents/ contains the agent itself: the persona, writing standard and journey prompts (persona.ts, prompts.ts), the tools that supply every fact and perform every delivery (tools.ts), the article layout renderer (layout.ts), the Deep Agent assembly (agent.ts), and the runGraphWorkflow() compatibility layer (graph.ts). layout.ts is deliberately pure — it does no I/O and knows nothing about MCP or image generation — so the interesting cases are cheap to test.
• protocol/ contains the ACP-specific JSON-RPC request/response handling used only by src/index.ts.
• storage/ contains the two persistence backends: a local SQLite checkpointer used by every entrypoint, and an S3 wrapper used for cloud state storage (with a transparent in-memory fallback).
• utils/ contains cross-cutting helpers with no dependency on any specific entrypoint or protocol: logging, LangChain message type guards, LLM client construction, MCP thread ids, and the publishing side — blog-mcp.ts drives the blog's own articles server, while image-gen.ts and illustration-styles.ts produce the pictures. Everything on that publishing side fails softly: a missing image costs a picture, never the article.