Frontend Architecture

The EpsimoAI frontend is a Next.js application providing the dashboard UI for managing AI assistants, projects, and conversations.

Tech Stack

Technology Purpose
Next.js 14+ (App Router) Framework, SSR, routing
React 18+ UI components
TypeScript Type safety
Tailwind CSS Styling
CSS Modules Component-scoped styles

Directory Structure

src/
├── app/
│   ├── layout.tsx              # Root layout
│   ├── providers.tsx           # Context providers wrapper
│   ├── globals.css             # Global Tailwind styles
│   ├── (auth)/                 # Auth route group
│   │   ├── layout.tsx          # Auth layout (centered, minimal)
│   │   ├── login/              # /login page
│   │   └── signup/             # /signup page
│   ├── (dashboard)/            # Dashboard route group (authenticated)
│   │   ├── layout.tsx          # Sidebar + header layout
│   │   ├── page.tsx            # / (dashboard home)
│   │   ├── projects/           # /projects management
│   │   ├── assistants/         # /assistants CRUD
│   │   ├── threads/            # /threads list + detail
│   │   ├── tools/              # /tools configuration
│   │   ├── settings/           # /settings page
│   │   └── admin/              # /admin panel
│   └── api/
│       └── clients/            # API route handlers (BFF)
├── components/
│   ├── ui/                     # Reusable UI primitives
│   │   ├── Button/
│   │   ├── Card/
│   │   ├── Input/
│   │   ├── Modal/
│   │   └── FileUpload/
│   └── ProjectSelector/        # Project switcher component
├── contexts/
│   ├── AuthContext.tsx          # JWT auth state, login/logout
│   └── ProjectContext.tsx       # Active project state
└── lib/
    ├── api-client.ts           # HTTP client (fetch wrapper, auth headers)
    └── types/
        └── api.d.ts            # Generated API types (OpenAPI → TypeScript)

Key Routes

Route Description
/login Email/password and Google OAuth login
/signup New account registration
/ (dashboard) Overview / home page
/projects List and manage projects
/assistants Create/edit AI assistants
/threads Conversation list, open thread detail
/threads/[id] Chat interface with streaming
/tools Configure tools for assistants
/settings User settings, API keys
/admin Admin panel (cleanup, user management)

The (auth) and (dashboard) route groups use different layouts — auth pages are minimal centered forms, while dashboard pages include a sidebar navigation.

Authentication Flow

  1. AuthContext stores the JWT token in localStorage
  2. api-client.ts attaches Authorization: Bearer <token> to all requests
  3. On Google OAuth callback, the backend redirects to /auth-callback?token=JWT (handled by the frontend)
  4. Protected routes check AuthContext and redirect to /login if unauthenticated

Build-Time Environment Variables

Variable Purpose Example
NEXT_PUBLIC_API_URL Backend API base URL (baked at build time) https://backend.epsimoagents.com

Since NEXT_PUBLIC_* variables are inlined at build time, changing the backend URL requires a rebuild and redeploy.

Docker Build

# Multi-stage build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build  # Produces .next/standalone output

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

The build uses Next.js standalone output mode for minimal image size.

Deployment

API Communication

The frontend communicates with the backend exclusively via HTTP: - REST calls for CRUD operations (projects, assistants, threads) - SSE (Server-Sent Events) for streaming chat responses - All requests go through the ALB at https://backend.epsimoagents.com