obsidian/01 Projects/semblance/DEVELOPER_MANUAL.md

auto_generated	created	manual_updated_at	modified	name	status	tags	type
true	2026-05-18	2026-05-18	2026-05-18	Developer_Manual	active	domain/ai domain/security tech/azure-ad tech/docker tech/express tech/gemini tech/jwt tech/mongodb tech/msal tech/node tech/react tech/reactive tech/socket-io tech/socket.io-client tech/sonner tech/tanstack-query tech/typescript type/sop	sop

Semblance Synthetic Society — Developer Manual

Architecture Overview

Semblance is a full-stack web application with a React frontend and a Node.js backend, communicating with a MongoDB database and external LLM providers. The application is containerized using Docker and Docker Compose for development and production environments.

High-Level Diagram

[Frontend (React/TS)] <--> [Backend (Node/Express)] <--> [MongoDB]
       ^                           ^
       |                           |
[LLM Providers]          [Auth Middleware]

Tech Stack

• Frontend:
  • React 18+ with TypeScript
  • React Router DOM for routing
  • TanStack Query for server state management
  • Socket.IO Client for real-time WebSocket communication
  • Sonner for toast notifications
  • Azure MSAL React for Microsoft Authentication
  • Tailwind CSS (implied by UI component structure)
• Backend:
  • Node.js
  • Express (implied by API structure)
  • Mongoose (MongoDB ODM)
  • Socket.IO Server
  • JWT for local authentication
• Infrastructure:
  • Docker & Docker Compose
  • MongoDB 7

Local Setup

Prerequisites

• Node.js 20+
• Docker and Docker Compose
• npm or yarn

Installation Steps

1. Clone the Repository

   git clone <repo-url>
   cd semblance
   

2. Configure Environment Variables

   • Copy .env.example to backend/.env:

     cp backend/.env.example backend/.env
     

   • Edit backend/.env to set:
     • MONGO_URI: Connection string to MongoDB (defaults to mongodb://mongo:27017/semblance_db in Docker).
     • JWT_SECRET: A strong secret for JWT token signing.
     • LLM_API_KEYS: API keys for Google Gemini and OpenAI.
     • MSAL_CONFIG: Client ID and tenant ID for Microsoft Authentication.

3. Start Infrastructure

   docker-compose up -d mongo
   

   This starts the MongoDB service with persistent volumes.

4. Build and Start Backend

   docker-compose up --build backend
   

   The backend will connect to MongoDB and start on port 5137.

5. Build and Start Frontend

   docker-compose --profile build up --build frontend
   

   The frontend builds and serves the output to ./backend/dist-out (or your configured dist directory). For local development with hot reload, you may need to run the frontend locally with npm run dev instead of the Docker build profile.

6. Access the Application

   • Frontend: http://localhost:5173 (if running locally) or via the configured proxy.
   • Backend API: http://localhost:5137.
   • MongoDB: 127.0.0.1:27017.

Environment Variables

Variable	Description	Required
MONGO_URI	MongoDB connection string	Yes
JWT_SECRET	Secret key for JWT signing	Yes
GEMINI_API_KEY	Google Gemini API key	Yes
OPENAI_API_KEY	OpenAI API key	Yes
MSAL_CLIENT_ID	Azure AD App Client ID	Yes
MSAL_TENANT_ID	Azure AD Tenant ID	Yes
NODE_ENV	Environment (development/production)	No

Key Services & Entry Points

Frontend Entry Points

• src/main.tsx: Root component initialization.
• src/App.tsx: Defines routing structure, providers (Auth, WebSocket, QueryClient), and route definitions.
  • Routes:
    • /: Index page.
    • /login: Authentication page.
    • /synthetic-users: Persona management.
    • /focus-groups: Session management.
    • /dashboard: Overview analytics.
    • /admin: Admin panel (protected).
• src/contexts/:
  • AuthContext.tsx: Handles local login and Microsoft SSO state. Uses localStorage for token persistence.
  • NavigationContext.tsx: Manages app state for navigation history and focus group context, persisted in localStorage.
  • WebSocketContextNew.tsx: Initializes a singleton Socket.IO instance. Uses a module-level socketInitialized flag to prevent re-initialization.

Backend Entry Points

• backend/: Contains the Express server, routes, and controllers.
• Services:
  • llm: Handles interactions with Gemini and OpenAI models.
  • aiRunner: Orchestrates autonomous focus group logic.
  • themeExtractor: Processes session transcripts for key themes.

WebSocket Implementation

• Service: src/services/websocketServiceNew.ts (referenced in context).
• Pattern: Singleton pattern via socketInitialized flag.
• Authentication: Socket connection is authenticated via JWT token passed in the auth_token from localStorage or the AuthContext.

API Reference

Authentication Endpoints

• POST /api/auth/login: Local login. Expects { username, password }. Returns JWT.
• POST /api/auth/microsoft: Microsoft SSO callback. Expects ID token. Returns JWT and user details.

Persona Endpoints

• GET /api/personas: List all personas.
• POST /api/personas: Create a new persona.
• PUT /api/personas/:id: Update a persona.
• GET /api/personas/:id: Get persona details.

Focus Group Endpoints

• POST /api/focus-groups: Create a session.
• GET /api/focus-groups/:id/stream: WebSocket events for session data.

Admin Endpoints

• GET /api/admin/users: List users.
• DELETE /api/admin/users/:id: Remove a user.

Deployment

Production Build

1. Ensure MONGO_URI points to the production MongoDB instance.
2. Set NODE_ENV=production.
3. Build the frontend using the Docker compose build profile:

   docker-compose --profile build up --build frontend
   

4. Deploy the backend container and frontend static assets to your web server (e.g., Nginx) or use a PaaS.

Docker Compose Notes

• The frontend service in docker-compose.yml is configured for build only. It copies the built assets to /app/dist-out. The backend should serve these static files in production.
• Volumes are used for MongoDB data persistence and backend uploads.

Known Gotchas

1. WebSocket Singleton Issue: The WebSocketContextNew.tsx uses a module-level socketInitialized flag. If the app is hot-reloaded in development, the flag may not reset, causing connection issues. In production, this is generally safe, but ensure server-side disconnects are handled if the client navigates away.

2. Navigation State Persistence: The NavigationContext persists state to localStorage. If a user switches browsers or clears storage, navigation history (like "Previous Route") will be lost. This may cause back-button issues if not handled gracefully in UI components.

3. Microsoft SSO Redirect: The MSAL handleRedirectPromise is called in AuthContext on mount. Ensure the redirect URI is correctly registered in Azure AD and matches the application's configuration.

4. Mention Parsing Regex: The parseMentions function uses a specific regex for @mentions. Be aware that complex names with special characters or punctuation may not be parsed correctly. The regex stops at conjunctions (and, or) and non-word boundaries.

5. Port Binding: Backend and MongoDB are bound to 127.0.0.1 in docker-compose.yml. This ensures they are not exposed to the public internet, but requires port forwarding or a reverse proxy for remote access.

Related

• 01 Projects/sandbox-notebookllamalm-nextjs/DEVELOPER_MANUAL.md