Skip to main content

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

TechnologyPurpose
Next.js 14React framework with App Router
TypeScriptType safety
Tailwind CSSStyling
Auth0 React SDKAuthentication
React QueryServer 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

TechnologyPurpose
Express.jsHTTP server
MongoDBDatabase
MongooseODM
Auth0Authentication
OpenAIAI processing
AWS S3File 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

{
  _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

{
  _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.