┌─────────────────────────────────────────────────────────────┐
│                    CLIENT LAYER                             │
│  ┌──────────────┐  ┌──────────────┐                         │
│  │   Website    │  │   Extension  │                         │
│  │  (Next.js)   │  │  (Vite/CRX)  │                         │
│  └──────┬───────┘  └──────┬───────┘                         │
└─────────┼─────────────────┼──────────────────────────────────┘
          │                 │
          └─────────────────┼──────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 API GATEWAY / LOAD BALANCER                 │
│              (Firebase Auth + GCP Load Balancer)            │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  APPLICATION LAYER                          │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │           ARCANE BACKEND (Express + TypeScript)       │ │
│  │                                                       │ │
│  │  Middleware Chain:                                    │ │
│  │  Auth → RateLimit → Context → Preware → Handler       │ │
│  │                      → Postware → Analytics           │ │
│  └───────────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────────┐ │
│  │        SESSION MANAGER (Real-time State Sync)         │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     DATA LAYER                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Firestore   │  │    Redis     │  │   GCP Storage    │  │
│  │  (Primary)   │  │   (Cache)    │  │   (Files)        │  │
│  └──────────────┘  └───────┬──────┘  └──────────────────┘  │
└────────────────────────────┼────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                  EXTERNAL AI PROVIDERS                      │
│  OpenAI • Anthropic • Google • Meta • Mistral • Fal AI    │
└─────────────────────────────────────────────────────────────┘

bonkers/
├── apps/
│   ├── website/           # Next.js web application
│   ├── extension/         # Chrome extension (Vite)
│   ├── arcane/            # Backend API server
│   └── session-manager/   # Session state service
│
├── packages/
│   ├── app-config/        # Shared configuration
│   ├── components/        # React components
│   ├── hooks/             # React hooks
│   ├── types/             # TypeScript types
│   ├── utils/             # Utilities
│   ├── config/            # ESLint/Prettier/TS configs
│   └── assets/            # Static assets
│
├── docs/                  # Documentation
├── patches/               # npm patches
├── package.json           # Root package.json
├── pnpm-workspace.yaml    # Workspace config
├── turbo.json            # Turborepo config
└── .github/               # GitHub configs

{
  "name": "cauldron",
  "packageManager": "pnpm@9.15.5",
  "engines": { "node": "^20", "pnpm": ">=9" },
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "init": "git submodule update --init --recursive && pnpm i",
    "lint": "turbo run lint"
  }
}

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": { "cache": false, "persistent": true },
    "lint": { "dependsOn": ["^lint"] }
  }
}

packages:
  - "apps/*"
  - "packages/*"

// middleware.ts
1. Clear old auth cookies
2. Check authentication state
3. Block routes based on auth (guest, emailNotVerified, normal)
4. Apply locale prefix (i18n)
5. Redirect unauthorized access

┌─────────────────┐
│  Background     │ ← Service worker (persistent)
│  Service Worker │
└────────┬────────┘
         │ Messages
         ▼
┌─────────────────┐
│  Content        │ ← Injected into all URLs
│  Scripts        │
└────────┬────────┘
         │ DOM Access
         ▼
┌─────────────────┐
│  Web Page       │
│  (Any URL)      │
└─────────────────┘

import { createServer } from "express-zod-api";
import { config } from "./config/config";
import { routing } from "./config/routing";

if (isDevEnv) {
  await generateTypes();
  await generateDocumentation();
}

await createServer(config, routing);

apps/arcane/src/
├── config/
│   ├── config.ts           # Server config, CORS, Swagger
│   ├── logger.ts           # Pino logger
│   └── routing.ts          # ALL API routes
├── server/
│   ├── constantsSchemasAndTypes/  # Zod schemas, types
│   ├── endpoints/          # Route handlers
│   ├── factories/          # Endpoint factories
│   ├── middlewares/        # Request middlewares
│   ├── models/             # Business logic models
│   ├── repositories/       # Data access layer
│   ├── services/           # External integrations
│   └── utilities/          # Helpers
└── index.ts

// apps/arcane/src/server/endpoints/unified/unified.ts
export const unified = timedAuthStreamEndpointsFactory
  .addMiddleware(usageLimitsMiddleware)      // 1. Check quotas
  .addMiddleware(threadPreware)              // 2. Setup context
  .addMiddleware(providerConfigOverride)     // 3. Model overrides
  .addMiddleware(unifiedController)          // 4. Main logic
  .addMiddleware(threadPostware)             // 5. Post-processing
  .addMiddleware(usageAnalyticsMiddleware)   // 6. Track usage
  .build({...});

// Sets up AsyncLocalStorage for request context
const storage = new AsyncLocalStorage<RequestContext>();

export const initContext = (req, res, next) => {
  const context = { requestId: randomUUID(), startTime: Date.now() };
  storage.run(context, () => next());
};

// 1. Extract JWT from Authorization header
// 2. Verify with Firebase Admin SDK
// 3. Create User instance, load from Firestore
// 4. Check/update user status
// 5. Store in request context

// 1. Check monthly usage < limit
// 2. Check daily usage < limit
// 3. Reset if reset time passed
// 4. Throw 429 if exceeded

// CRITICAL: Sets up entire request context
// 1. Determine API version (V1/V2)
// 2. Load user settings
// 3. Initialize/load thread
// 4. Load personalization
// 5. Start async side actions
// 6. Initialize SSE stream
// 7. Process attachments
// 8. Create message nodes
// 9. Start content moderation
// 10. Calculate context window
// 11. Load history with embeddings
// 12. Initialize Schema
// 13. Store in request context
// 14. Update thread

interface RequestContext {
  user: TUserDoc;
  userInstance: User;
  chatNode: Thread;
  userMessageNode: Message;
  assistantMessageNode: Message;
  schema: Schema;
  eventManager?: EventManager;
  settingsV3: TSettings;
  personalization: TPersonalization;
  executionContext: 'USER' | 'TASK';
}

// Access anywhere after initContext
import { requestContext } from '../repositories/context/requestContext';
const { user, chatNode } = requestContext.get();

class User {
  decodedToken: DecodedIdToken;
  user: TUserDoc | null;
  uid: string | null;
  shouldUpdate: boolean;

  async init() {
    // 1. Get user from Firebase Auth
    // 2. Load user document from Firestore
    // 3. Handle guest → free conversion
    // 4. Check email verification
    // 5. Handle temporary Pro rewards
  }

  async updateUser() {
    // Save to Firestore if shouldUpdate
  }
}

class Thread implements TChatDB {
  chatId: string;
  threadMap: Map<string, Message>;
  ref: DocumentReference;

  static async init(chatId, createNew, config) {
    // Load from Firestore, repair orphans, create if missing
  }

  async getActiveThreadWithEmbeddings(messageId, query, contextWindow) {
    // Traverse backwards, accumulate messages, query embeddings
  }

  async update({ userMessage, assistantMessage }, options) {
    // Save to Firestore with conflict retry logic
  }
}

const storage = new AsyncLocalStorage<RequestContext>();

export const requestContext = {
  get() { return storage.getStore() || {}; },
  set(context) {
    const store = storage.getStore() || {};
    Object.assign(store, context);
  }
};

class Schema {
  schema: TSchema;

  setModel(model: TLLMModels, basedOnPlan: boolean) {
    this.schema.model = model;
    this.setMaxTokens(basedOnPlan);
  }

  injectPrompt({ message, messages, prompt, variables }) {
    // Add system/user messages, validate placeholders
  }
}

// Run async operation (non-blocking)
sideActions.run(ActionTypes.CONTENT_MODERATION);

// Run with custom handler
sideActions.runCustom(fn, args, actionType);

// Wait for result (blocking)
const result = await sideActions.wait(ActionTypes.SELECT_MODEL);

// Initialize SSE
const init = (response: Response) => {
  response.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  });
};

// Stream chunks
const stream = async (req, response, inputStream) => {
  // Process chunks, send SSE events
};

// End stream
const end = async (response: Response) => {
  response.write(getMessage(END_MESSAGE));
  response.end();
};

// Redis pub/sub for cross-request communication
class InterRequestCommunicator {
  static async addSubscription(ircId, callback) {
    await this.redisSub.subscribe(channelId);
    this.subList.set(channelId, callback);
  }

  static async sendMessage(ircId, message) {
    await redisPub.publish(channelId, JSON.stringify(payload));
  }
}

interface TUserDoc {
  uid: string;
  email: string;
  role: 'guest' | 'free' | 'paid' | 'member' | 'owner' | 'tools';
  userPlan: 'GUEST' | 'FREE' | 'PRO' | 'PRO_TEMP' | 'TOOLS';
  provider: 'anonymous' | 'google' | 'microsoft' | 'apple';
  photoUrl: string;

  monthlyUsage: {
    cost: number;
    resetsAt: number;
    models?: Record<string, number>;
  };
  dailyUsage: {
    cost: number;
    resetsAt: number;
    models?: Record<string, number>;
  };

  settings?: TUserSettings;
  preferences?: TUserPreferences;
  connectedApps?: { gdrive?: {...} };
  connectedComposioApps?: Record<string, any>;
  notificationTokensByDeviceId?: Record<string, any>;
  topUps?: Array<{ amount: number; expiresAt: number }>;
}

interface TChatDB {
  chatId: string;
  userId: string;
  projectId?: string;
  mode: TChatModes;
  metadata: {
    title?: string;
    folderId?: string;
    chatbot?: { id: string; name: string };
    projectId?: string;
  };
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

interface TMessageDBV2 {
  id: string;
  chatId: string;
  parentId?: string;
  childrenId: string[];
  role: 'user' | 'assistant' | 'system';
  contentV2: TMessageContentV2;
  modelId?: TLLMModels;
  timestamp: Timestamp;
  tokens: number;
  attachments?: TAttachment[];
  isPending: boolean;
  error?: { type: ErrorType; message: string };
}

type TMessageContentV2 = Array<
  | { type: 'TEXT'; text: string; tokens: number; reasoning?: string }
  | { type: 'TOOL_RESULT'; toolResults: Array<{ name: string; content: string; tokens: number }> }
  | { type: 'PROGRESS'; name: string; icon: string; steps: TProgressStep[]; metadata?: any }
>;

// apps/arcane/src/server/constantsSchemasAndTypes/wallflower/templates.constants.ts
export const TEMPLATES = {
  "ghibli-style": {
    id: "ghibli-style",
    name: "Ghiblify",
    preset: {
      prompt: "turn this into ghibli style",
      style: "Auto",
      modelConfig: {
        modelId: "gpt-image-1-medium",
        numberOfImages: 1,
      },
    },
  },
  // ... more templates
} as const;

case "TEMPLATE":
  switch (feature.templateId) {
    case "product-photography":
      formattedImage = await handleProductPhotographyTemplate({...});
      break;
    // ... other templates
  }

export async function callWithFallback<T, U>(
  primaryFunc: T,
  fallbackFunc: U,
): Promise<Awaited<ReturnType<T> | ReturnType<U>>> {
  try {
    const res = await primaryFunc();
    return res;
  } catch (error) {
    logger.error(error, "ERROR/PRIMARY_FUNCTION_FAILED");
    return await fallbackFunc();
  }
}

// endpoints/wallflower/helpers/fal-ai.ts
export async function handleFalWithReplicateFallback({...}) {
  return await callWithFallback(
    async () => await callFalAI({...}),
    async () => await callReplicate({
      modelId: FALLBACK_MODELS_MAP[feature.modelConfig.modelId],
      ...
    })
  );
}

// endpoints/wallflower/helpers/replicate.ts
export async function handleReplicateWithFalAIFallback({...}) {
  return await callWithFallback(
    async () => await callReplicate({...}),
    async () => await callFalAI({
      modelId: FALLBACK_MODELS_MAP[feature.modelConfig.modelId],
      ...
    })
  );
}

export const FALLBACK_MODELS_MAP = {
  // Maps primary models to fallback equivalents
};

// Helper function with fallback chain
async function scrapeWithFallbackMethod(urls: string[]) {
  try {
    // Try Firecrawl first
    const result = await firecrawl.scrape(urls);
    return result;
  } catch (error) {
    logger.error(error, "ERROR/DEEP_RESEARCH/FALLBACK_SCRAPING");
    // Fall back to basic fetch
    return await basicFetch(urls);
  }
}

// Parallel Google search fallback if Bing fails
try {
  const results = await bingSearch(queries);
} catch (error) {
  logger.error("ERROR/DEEP_RESEARCH/GOOGLE_SEARCH_FALLBACK");
  const results = await googleSearch(queries);
}

async detectWithFallback(text: string): Promise<{...}> {
  try {
    return await primaryDetectionAPI(text);
  } catch (error) {
    return await secondaryDetectionAPI(text);
  }
}

const FALLBACK_ATTACHMENT_KEY = "DOCUMENT_CHUNK";

const getChunksFromFallbackLIResults = (embeddings: TLIResult[]): string[] => {
  // Fallback for items without attachmentId/nodeIndex (old embeddings)
  const fallbackKey = `${item.attributes?.name ?? FALLBACK_ATTACHMENT_KEY}`;
  // Group and return chunks
};

// Used when:
// 1. New embedding format not available
// 2. attachmentId missing
// 3. nodeIndex missing (legacy embeddings)

const inferenceFallbackOutput = 
  // Fallback model selection logic when primary inference fails
  return inferenceFallbackOutput;

logger.error("ERROR/IMAGE_INFERENCE_FALLBACK");

// Commented out but documented fallback strategy
// const CACHE_FALLBACK_QUERY_CONSUMED = 2;
// const CACHE_FALLBACK_TOKENS_CONSUMED = 1000;
// Fallback when primary transcription method fails

const MAX_FALLBACK_CHAR_LIMIT = 20000; // approx. 5k tokens

// Truncate tool results to fit within limit
if (result.length > MAX_FALLBACK_CHAR_LIMIT) {
  result = result.substring(0, MAX_FALLBACK_CHAR_LIMIT);
}

// Default fallback index for tool results as progress events
export const DEFAULT_FALLBACK_INDEX = 0;

Client → Firebase Auth → JWT → Backend verifies → Firestore user doc

process.on("uncaughtException", (err) => {
  logger.error(err, "ERROR/COMPLETE_INSTANCE_FAILURE");
  setTimeout(() => process.exit(1), 20000);
});

try {
  await riskyOperation();
} catch (error) {
  if (error instanceof ClientError) throw error;
  logger.error(error, "ERROR/OPERATION_FAILED");
  throw new ServerError(500, ErrorType.INTERNAL_SERVER_ERROR);
}

let messageIncrement = 0;
while (trying) {
  try {
    const batch = db.batch();
    this.setMessage(batch, userMessage, this.totalDocs + messageIncrement);
    await batch.commit();
    trying = false;
  } catch (err) {
    if (messageIncrement === 3) throw MAX_RETRY_ERROR;
    messageIncrement++;
  }
}

steps:
  - Build Docker image with Kaniko
  - Push to GCR
  - Deploy to Cloud Run (arcane, arcane-copy, arcane-deepresearch)

FIREBASE_PROJECT_ID=foyer-work
OPENAI_API_KEY=sk-...
REDIS_HOST=localhost

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXTAUTH_SECRET=...

# Backend
gcloud run services update arcane --to-revisions=arcane-abc123=100

# Website
vercel rollback [deployment-url]

let messageIncrement = 0;
while (trying) {
  try {
    const batch = db.batch();
    this.setMessage(batch, msg1, this.totalDocs + messageIncrement);
    this.setMessage(batch, msg2, this.totalDocs + messageIncrement);
    await batch.commit();
    trying = false;
  } catch (err) {
    if (messageIncrement === 3) throw error;
    messageIncrement++;
  }
}

const shardId = hash(userId) % NUM_SHARDS;
const db = getFirestoreShard(shardId);

const queue = new Queue('llm-calls', {
  redis: redisCluster,
  defaultJobOptions: { attempts: 3, backoff: 'exponential' }
});

const cacheKey = hash(prompt + model + settings);
const cached = await redis.get(cacheKey);
if (cached) return cached;

const openaiBreaker = new CircuitBreaker(callOpenAI, {
  timeout: 30000,
  errorThresholdPercentage: 50,
  resetTimeout: 60000
});

async function callLLM(prompt, model) {
  try {
    return await openaiBreaker.fire(prompt);
  } catch (error) {
    if (openaiBreaker.opened) {
      return await anthropicBreaker.fire(prompt); // Fallback
    }
    throw error;
  }
}

const rateLimits = {
  GUEST: { points: 50, duration: 900 },
  FREE: { points: 100, duration: 60 },
  PRO: { points: 500, duration: 60 },
};

const endpointLimits = {
  '/v1/thread/unified': { multiplier: 1 },
  '/v1/tools/image': { multiplier: 5 },
  '/v1/deep-research': { multiplier: 10 }
};

async function rateLimit(req, user) {
  const limit = rateLimits[user.userPlan];
  const cost = limit.points * endpointLimits[req.path].multiplier;
  await rateLimiter.consume(user.uid, cost);
}

const sanitized = input
  .replace(/ignore previous instructions/gi, '')
  .replace(/system prompt/gi, '');

const prompt = `
<system>You are a helpful assistant</system>
<user-input>${escapeXml(userInput)}</user-input>
<instructions>Only respond to user-input above</instructions>
`;

if (output.includes('system prompt')) {
  throw new ClientError(400, ErrorType.INPUT_NOT_MODERATED);
}

getMessages() {
  let parent = this.threadMap.get('root');
  const messages = [];
  while (parent) {
    const child = this.threadMap.get(parent.childrenId[0]);
    messages.push(child.getMessage());
    parent = child;
  }
  return messages;
}

interface TChatDB {
  recentMessages: TMessageDBV2[];  // Last 10
  totalMessages: number;
}

interface TChatDB {
  firstMessageId: string;
  lastMessageId: string;
  messageIndex: Map<string, { prev: string; next: string }>;
}

await db.runTransaction(async (transaction) => {
  const chat = await transaction.get(chatRef);
  if (chat.data().version !== clientVersion) {
    throw new ConflictError('Chat modified by another device');
  }
  transaction.update(chatRef, { version: clientVersion + 1 });
});

await chatQueue.add(chatId, { message, userId });
// Processed sequentially per chatId

const cached = await redis.get(`session:${token}`);
if (cached) return JSON.parse(cached);
const user = await verifyToken(token);
await redis.setex(`session:${token}`, 300, JSON.stringify(user));

try {
  await db.collection('chats').doc(id).get();
} catch (error) {
  return cachedChats.get(userId);
}

# Local Development
pnpm dev                    # Start all apps
pnpm build                  # Build everything

# Backend (port 8080)
cd apps/arcane && pnpm dev

# Website (port 3001)
cd apps/website && pnpm dev

# Extension
cd apps/extension && pnpm dev