mistral-reference-architecture

name	mistral-reference-architecture
description	Implement Mistral AI reference architecture with best-practice project layout. Use when designing new Mistral AI integrations, reviewing project structure, or establishing architecture standards for Mistral AI applications. Trigger with phrases like "mistral architecture", "mistral best practices", "mistral project structure", "how to organize mistral".
allowed-tools	Read, Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","mistral","mistral-reference"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Mistral AI Reference Architecture

Overview

Production-ready architecture patterns for Mistral AI integrations: layered project structure, singleton client, Zod-validated config, custom error classes, service layer with caching, health checks, prompt templates, and model routing.

Prerequisites

• TypeScript/Node.js project (ESM)
• @mistralai/mistralai SDK
• zod for config validation
• Testing framework (Vitest)

Layer Architecture

API Layer (Routes, Controllers, Middleware)
    |
Service Layer (Business Logic, Orchestration)
    |
Mistral Layer (Client, Config, Errors, Prompts)
    |
Infrastructure Layer (Cache, Queue, Monitoring)

Instructions

Step 1: Directory Structure

src/
├── mistral/
│   ├── client.ts         # Singleton client factory
│   ├── config.ts         # Zod-validated config
│   ├── errors.ts         # Custom error classes
│   ├── types.ts          # Shared types
│   └── prompts.ts        # Prompt templates
├── services/
│   ├── chat.service.ts   # Chat with caching + retry
│   ├── embed.service.ts  # Embeddings + search
│   └── rag.service.ts    # RAG pipeline
├── api/
│   ├── chat.route.ts     # HTTP endpoints
│   └── health.route.ts   # Health check
└── config/
    ├── base.ts           # Shared config
    ├── development.ts    # Dev overrides
    └── production.ts     # Prod overrides

Step 2: Config with Zod Validation

// src/mistral/config.ts
import { z } from 'zod';

const MistralConfigSchema = z.object({
  apiKey: z.string().min(10, 'MISTRAL_API_KEY required'),
  defaultModel: z.string().default('mistral-small-latest'),
  timeoutMs: z.number().default(30_000),
  maxRetries: z.number().(),
  : z.({
    : z.().(),
    : z.().(),
    : z.().(),
  }).({}),
});

   = z.< >;

  ():  {
   .({
    : process..,
    : process..,
    : process.. ? (process..) : ,
  });
}