---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- 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
type: 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**
   ```bash
   git clone <repo-url>
   cd semblance
   ```

2. **Configure Environment Variables**
   - Copy `.env.example` to `backend/.env`:
     ```bash
     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**
   ```bash
   docker-compose up -d mongo
   ```
   This starts the MongoDB service with persistent volumes.

4. **Build and Start Backend**
   ```bash
   docker-compose up --build backend
   ```
   The backend will connect to MongoDB and start on port `5137`.

5. **Build and Start Frontend**
   ```bash
   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:
   ```bash
   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]]