> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adminest.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Understanding the Adminest codebase structure

## High-Level Architecture

Adminest follows a modern full-stack architecture with clear separation of concerns:

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Frontend     │────▶│     Backend     │────▶│    Services     │
│   (Next.js)     │     │   (Express)     │     │  (AI, Storage)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │    MongoDB      │
                        └─────────────────┘
```

## Directory Structure

```
adminest/
├── frontend/                 # Next.js application
│   ├── src/
│   │   ├── app/             # App router pages
│   │   ├── components/      # React components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # Utilities and API client
│   │   └── styles/          # CSS and Tailwind
│   └── public/              # Static assets
│
├── backend/                  # Express API server
│   ├── routes/              # API route handlers
│   ├── models/              # Mongoose schemas
│   ├── services/            # Business logic
│   ├── middleware/          # Auth, validation, etc.
│   └── utils/               # Helper functions
│
├── docs/                     # Internal documentation
└── docs-public/              # Public documentation (Mintlify)
```

## Frontend Architecture

### Technology Stack

| Technology      | Purpose                         |
| --------------- | ------------------------------- |
| Next.js 14      | React framework with App Router |
| TypeScript      | Type safety                     |
| Tailwind CSS    | Styling                         |
| Auth0 React SDK | Authentication                  |
| React Query     | Server state management         |

### Key Components

```
components/
├── documents/
│   ├── DocumentList.tsx     # Document grid/list view
│   ├── DocumentUpload.tsx   # Upload dropzone
│   └── DocumentViewer.tsx   # PDF/image viewer
├── tasks/
│   ├── TaskList.tsx         # Task display
│   ├── TaskForm.tsx         # Create/edit tasks
│   └── TaskCalendar.tsx     # Calendar view
├── chat/
│   └── ChatInterface.tsx    # AI assistant UI
└── shared/
    ├── Layout.tsx           # Page layout
    ├── Sidebar.tsx          # Navigation
    └── Modal.tsx            # Reusable modal
```

## Backend Architecture

### Technology Stack

| Technology | Purpose        |
| ---------- | -------------- |
| Express.js | HTTP server    |
| MongoDB    | Database       |
| Mongoose   | ODM            |
| Auth0      | Authentication |
| OpenAI     | AI processing  |
| AWS S3     | File storage   |

### API Structure

Routes follow RESTful conventions:

```
routes/
├── auth.js          # Authentication endpoints
├── documents.js     # Document CRUD + upload
├── tasks.js         # Task management
├── chat.js          # AI assistant
├── calendar.js      # Calendar sync
├── categories.js    # Organization
└── connections.js   # Family sharing
```

### Services Layer

Business logic is separated into services:

```
services/
├── documentService.js       # Document processing
├── aiService.js             # OpenAI integration
├── storageService.js        # S3 operations
├── calendarService.js       # Google/Microsoft sync
├── taskService.js           # Task logic
└── weeklyDigestService.js   # Scheduled reports
```

## Data Models

### Document Schema

```javascript theme={null}
{
  _id: ObjectId,
  userId: String,              // Auth0 user ID
  originalFileName: String,
  documentType: String,        // AI-detected type
  processingStatus: String,    // pending|processing|completed|failed
  s3Key: String,               // Storage reference
  aiAnalysis: {
    summary: String,
    extractedData: Object,
    suggestedTasks: Array
  },
  categories: [ObjectId],
  sharedWith: [ObjectId],      // Connection references
  createdAt: Date,
  updatedAt: Date
}
```

### Task Schema

```javascript theme={null}
{
  _id: ObjectId,
  userId: String,
  title: String,
  description: String,
  dueDate: Date,
  status: String,              // pending|in_progress|completed
  priority: String,            // low|medium|high
  linkedDocument: ObjectId,
  categories: [ObjectId],
  calendarEventId: String,     // External calendar reference
  createdAt: Date,
  updatedAt: Date
}
```

## Authentication Flow

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  User    │────▶│  Auth0   │────▶│ Frontend │────▶│ Backend  │
│          │     │          │     │          │     │          │
│ 1. Login │     │ 2. Auth  │     │ 3. Token │     │ 4. Verify│
└──────────┘     └──────────┘     └──────────┘     └──────────┘
```

1. User clicks login
2. Auth0 handles authentication
3. Frontend receives JWT token
4. Backend validates token on each request

## AI Processing Pipeline

Document processing flow:

```
Upload ──▶ S3 Storage ──▶ Text Extraction ──▶ AI Analysis ──▶ Store Results
                              │
                              ▼
                         OCR (if image)
```

The AI service:

1. Extracts text from documents (OCR for images)
2. Analyzes content to determine document type
3. Extracts key data (dates, amounts, policy numbers)
4. Generates summary and suggested tasks
5. Creates vector embeddings for semantic search

## External Integrations

### Google Calendar

* OAuth 2.0 authentication
* Two-way sync for tasks with due dates
* Webhook notifications for external changes

### Microsoft Calendar

* Microsoft Graph API
* Similar flow to Google Calendar
* Supports Outlook and Microsoft 365

### AWS S3

* Secure document storage
* Pre-signed URLs for uploads/downloads
* Lifecycle policies for cost optimization

### AI Observability

The Admin Centre includes an AI tab that provides real-time visibility into Claude API usage via Langfuse integration:

* **Token tracking** — input, output, and cached token counts per operation
* **Cost estimation** — based on Claude Sonnet 4.5 pricing
* **Latency monitoring** — average response times by operation type
* **Per-user analytics** — consumption breakdown by user
* **Error rate tracking** — identify failing AI operations

Data is queried from Langfuse via the SDK's `traceList()` and `observationsGetMany()` APIs, with Redis caching (5-minute TTL) for performance.