MemberJunction Developer Guides

This folder is the home for cross-cutting, “read this before you build that” reference docs. Package-specific docs live in packages/<Pkg>/CLAUDE.md or packages/<Pkg>/README.md and are linked from here when relevant.

If you’re about to start work in one of the areas below, read the guide first — these documents capture patterns that have already been litigated.

Start here

• Building Applications on MemberJunction — The hub guide for using MJ as a first-class application development platform. Explains the metadata-driven, schema-to-app model, the unified-TypeScript / isomorphic object model, AI-native app patterns, and links out to the authoritative README/guide for every layer (data modeling, CodeGen, entities, API, UI, Actions, AI, deployment). Start here if you’ve got data in MJ and want to build on it.
• Framework Comparison — Objective comparison of MJ against Next.js/Vercel, Supabase, Rails, Django, and a hand-rolled Node+ORM+SPA stack: where each shines, where MJ differs, and how to choose. Companion to the app-building guide.
• Agent Framework Comparison — Objective comparison of MJ’s AI agent framework and infrastructure against LangGraph, CrewAI, AG2/AutoGen, the vendor agent SDKs, Semantic Kernel, LlamaIndex, and the TypeScript-native frameworks: orchestration paradigms, payload/state governance, HITL, model gateway, observability, memory, permissions, and deployment (self-host or managed via MJ Central). Companion to the app-stack comparison above.

Framework fundamentals

• BaseEntity Server-Side Patterns — Patterns for server-side BaseEntity subclasses: persisted embeddings, cross-record invariants via ValidateAsync, FK cleanup before delete. Read before writing a new entity subclass under MJCoreEntitiesServer.
• Soft Deletes Guide — How DeleteType='Soft' works end to end: CodeGen-managed __mj_DeletedAt column, filtered base views, soft-delete spDelete, interaction with AllowRecordMerge.
• UUID Comparison Guide — Critical: SQL Server returns UUIDs uppercase, PostgreSQL lowercase. Always use UUIDsEqual() / NormalizeUUID() instead of === for UUID comparisons.
• Caching & Real-Time Synchronization Guide — Multi-tier server caching, RunView cache behavior, BypassCache, BaseEntity event-driven invalidation, Redis pub/sub, real-time browser sync. Read before touching caching or write-after-write data flow.

Search, RAG, and tagging

• Search Scopes & RAG+ Guide — Implementation guide for Search Scopes + agent RAG+ architecture. Companion to plans/search-scopes-rag-plus.md.
• Content Autotagging Guide — The Knowledge Hub pluggable autotagging pipeline: providers, keyword extraction, taxonomy bridging.
• Taxonomy & Tagging Guide — How the tag taxonomy itself is shaped, scoped, governed, grown, embedded, reviewed, and pruned. Companion to the autotagging guide.

AI and agents

• Agent Memory Guide — The complete agent-memory architecture: three-tier mental model (scratchpad → provisional → hardened), note injection (strategies, recency-wins policy, dated rendering, 8-level scoping), in-flight memoryWrites (the guard pipeline, AllowMemoryWrite gating, AuthorType provenance), and the Memory Manager’s hardening/consolidation/contradiction/decay pipeline. Includes a configuration reference and troubleshooting queries.
• Real-Time Co-Agents Guide — Live, low-latency voice agents: the Realtime agent type and Realtime Co-Agent (one co-agent voices any target agent), the triple-registry plugin architecture (server/client model drivers + channel plugins), client-direct vs server-bridged topologies, session lifecycle/janitor, interactive channels (the live Whiteboard), narration, observability, and security. Companion to plans/ai-agent-sessions.md.
• Realtime Session Capture & Recording Guide — How a voice session is captured: per-turn transcript with start/end timing + speaker identity, and the optional audio recording. Covers the create-on-start/update-on-complete turn lifecycle, recording on both topologies (server-bridged mixer and client-direct browser capture via RealtimeAudioRecorder), the seekable 16-bit PCM WAV + capture-time peaks.json waveform sidecar, agent-audio mixing (AttachRemoteStream / OnRemoteMediaStream), and streaming playback via mj-storage-media-player → CreateMediaAccessToken → the GET /media/:fileId Range route. Read before touching persistRealtimeTranscript, the recording capture/store, or playback.
• Conversations UX Stack Guide — The 3-layer architecture for every chat surface: pure-TS @memberjunction/conversations-runtime (orchestration) ↔ adapters (INotificationAdapter / IActiveTaskTracker / ISessionsAdapter) ↔ @memberjunction/ng-conversations (Angular widget). Slot system, Before/After cancelable events, --mj-chat-* design tokens, default-agent resolution, sessions adapter bridging to realtime, recipes.

Angular / MJExplorer

• Dashboard Best Practices — Architecture, naming, state management with getter/setters, engine class patterns, user preferences, layout, permission checking for MJ dashboards.
• Lazy Loading Guide — How MJExplorer’s code-split lazy loading works, how to add new dashboard components, how to make a package lazy-loadable, the auto-generated lazy config.
• Navigation and Routing Guide — How the shell owns URL state, back/forward navigation, adding URL-synced sub-navigation to a component.
• Media Player package — The generic mj-media-player (zero-MJ-dep audio/video player: transport, real waveform scrubber, playback speed, ±skip, time-synced transcript, multi-track video grid) and the MJStorage-bound mj-storage-media-player wrapper (resolves an MJ: Files id to a permission-gated, Range-streamed /media URL with server-supplied waveform peaks). Used by the artifact audio/video viewers + previews and the realtime session-review overlay.

Theming and visual design

• Theming — Pointer page. Authoritative theming guide is co-located with ThemeService at packages/Angular/Generic/shared/THEMING.md.
• App Color Architecture — Why dashboards must not hardcode hex values; how to migrate to design tokens.

Completed / archived

The complete/ subdirectory holds guides whose subject matter has been fully implemented and absorbed into the codebase. Kept for historical context — newer guides should go in the top-level folder.

---

Adding a new guide

A topic earns a guide in this folder when:

1. It spans multiple packages or touches the framework as a whole — package-internal guidance belongs in that package’s CLAUDE.md.
2. It captures non-obvious patterns a developer would not derive by reading the code alone (gotchas, conventions, “why we do it this way”).
3. The patterns have been validated in production — speculative designs belong in plans/, not here.

When adding a guide, also:

• Add a one-line entry to this README under the appropriate section.
• If the guide is referenced often enough to be a hard requirement, add a pointer to it in the root CLAUDE.md under “Development Guides”.