Bike4Mind – High-Level Architecture

1. Landscape

• Mission – Bike4Mind (B4M) is a “cognetic workbench”: an AI-augmented environment for knowledge work, file handling, notebook-style chat, image generation and more.

• Core user journeys today
  – Chat & Notebooks (aka Sessions)
  – Mementos (personal memory objects)
  – File / Project / Notebook browsing & sharing
  – Credit / Subscription management

• Dynamic-UX vision – Let the user/agent co-create a bespoke, one-page “mini-app” (e.g. an RPG character sheet) on-the-fly, fully wired to B4M data and tools.

2. Tech-Stack Snapshot

Frontend
• Next.js 14 (both app & pages folders)
• JOY UI (MUI Joy) for the design system
• Zustand + React context providers for state
• TanStack Query for server-state fetching

Backend / API
• Next.js API Routes under packages/client/pages/api/** with an express-style wrapper baseApi() (see packages/client/server/middlewares/baseApi.ts lines 22-60)
• SST (Serverless Stack) v2: defines Lambda queues, cron jobs, WebSocket API, S3 buckets, etc. – largest config in root sst.config.ts (~1 300 lines)
• Persistence – MongoDB via Mongoose (b4m-core/packages/core/database/src/utils/mongo.ts lines 1-54)

Infra & DevOps
• AWS CDK through SST: VPC, CloudFront, Route53, SQS, Dynamo, Cron
• pnpm workspaces; linting via ESLint & Semgrep; CI via Seed.run + GitHub Actions

LLM / Agent Tooling
• Uses the official openai npm SDK (no LangChain/AutoGen)
• Model registry & pricing tables in b4m-core/packages/core/common/models.ts lines 1-160 handle OpenAI, Anthropic, Bedrock, Ollama, xAI, etc.
• SessionManager orchestrates chat completions & image generation (packages/client/server/managers/sessionManager.ts lines 1-200)

3. Repository Map (condensed)

.
├─ packages/
│  ├─ client/            ← Next.js app + server code
│  │  ├─ pages/          ← File-based routes & /api routes
│  │  ├─ app/            ← RSC & component library
│  │  └─ server/         ← Lambda handlers, middlewares, utils
│  ├─ services/          ← Shared TypeScript utilities
│  ├─ subscriber-fanout/ ← SQS fan-out service (Docker/ECS)
│  └─ database/          ← Local Mongo helpers & seed
├─ b4m-core/
│  └─ packages/core/
│      ├─ common/        ← Shared enums, zod schemas, TS types
│      ├─ database/      ← Mongoose models & utilities
│      ├─ services/      ← Pure domain services (import, counters…)
│      └─ utils/         ← Logger, SQS helper, etc.
└─ sst.config.ts         ← All AWS infra & routing glue

4. Core Domain Primitives

Agent
• Lives mainly in packages/client/server/managers/sessionManager.ts
• Handles chat → OpenAI call → store reply → queue side-jobs (summaries, image gen)

Memento
• Memory objects (IMemento) – see b4m-core/packages/core/common/types/entities/MementoTypes.ts
• Corresponding Mongoose model in b4m-core/packages/core/database/src/models/MementoModel.ts

File / AppFile
• Stored metadata + S3 paths; CRUD via /api/app-files/**

Project
• Aggregates Notebooks, Files, etc. – controllers in /api/projects/**

Notebook / Session
• Chat threads stored in Mongo sessions collection – rich helper methods for share/fork/snippet.

Credit / Billing
• Stripe integration via routes /api/stripe/**, models under b4m-core

Other entities – Users, Organizations, Invitations, Quests, Activities – follow the same repository pattern.

5. Current Data & Event Flow

Example edit-notebook happy-path:
Client Action → useApi (axios in ApiContext) injects JWT & idempotency →
API Route /api/sessions/update → baseApi() middleware (DB connect, auth, logger) →
Domain service sessionManager.updateSession touches Mongo →
Success response → WebSocket fan-out (packages/client/server/websocket/**) publishes change so subscribed clients update in < 1 s.
Errors surface via errorHandler middleware and client-side toast.

6. State Management & React Patterns

• Provider bundle in _app.tsx: ApiProvider → AccessToken → UserProvider → …
• TanStack Query + custom useSubscribeCollection merges WS deltas.
• Long-lived client state in small, typed Zustand stores (useSidebar, useLLM, etc.).
• Auth-dependent components show an ExpiredSession modal when context invalid.

7. Dynamic-UX Vision (current gaps)

Nothing yet auto-generates React code or JSON-driven layouts. Desired flow:

Chat command triggers agent tool-call.
Agent emits createDynamicView event → persists dynamic_views Mongo model → enqueues SQS job.
Client receives WS event and renders via a schema-driven Joy-UI renderer.

Security, latency & sharing follow existing JWT + CASL + WebSocket patterns.

8. Rendering & Composition Strategy (today vs future)

Today – Mostly CSR pages; some RSC under app/; Joy UI components static.

Future – Agent produces JSON schema → validated → rendered by a thin Joy UI renderer; TypeScript safety via zod-to-ts generation.

9. Agent Pipeline (implemented)

Chat prompt → SessionManager builds OpenAI request (+ optional function-calls) → external API call
• Success: store message, fire SQS jobs (fabFileVectorize, notebookSummarization, …) → WS update
• Failure: logged via Winston-style Logger, surfaces HTTP error to client.

10. Pain Points & Wishlist

• Migrate more context state to Zustand stores.
• Several TODO turn back on when we get these secrets in sst.config.ts.
• Error surfacing is still rough in some axios interceptors.
• Dynamic layout/drag-drop builder not started.
• Need runtime validation for agent-generated views.

11. Constraints & Non-Goals

• Coding rules enforced (auth-aware API calls, error boundaries, strict typing).
• sst.config.ts sets custom domains & secrets but no hard geo-residency yet.
• Mobile/offline experiences currently out of scope – web-desktop first.

Key Take-aways for Dynamic-UX Implementation

WebSocket foundation is already in place; pushing a DynamicView schema via existing topics is straightforward.
Extend SessionManager so the agent can emit/queue Dynamic-UI specs.
Client introduces <DynamicViewRenderer viewId="…" /> with Joy-UI widgets.
Maintain type safety by generating zod schemas → ts interfaces.
Build a library of Joy-UI "frame components" (SpreadsheetGrid, AvatarRenderer, MarkdownBlock, …) that the agent can reference by name.

This shared context should support deeper design of fully agent-driven, chat-initialised Dynamic UIs within Bike4Mind.

1. Landscape​

2. Tech-Stack Snapshot​

3. Repository Map (condensed)​

4. Core Domain Primitives​

5. Current Data & Event Flow​

6. State Management & React Patterns​

7. Dynamic-UX Vision (current gaps)​

8. Rendering & Composition Strategy (today vs future)​

9. Agent Pipeline (implemented)​

10. Pain Points & Wishlist​

11. Constraints & Non-Goals​

Key Take-aways for Dynamic-UX Implementation​