Screens & Routes

Route Map

Sentinel exposes 11 frontend routes organised into two layout groups: (auth) for unauthenticated pages and (dashboard) for the authenticated app shell.

#	Route	Service	Auth Required	Layout Group	File
1	`/`	–	Yes (redirect)	root	`app/src/app/page.tsx`
2	`/login`	Auth	No	`(auth)`	`app/src/app/(auth)/login/page.tsx`
3	`/register`	Auth	No	`(auth)`	`app/src/app/(auth)/register/page.tsx`
4	`/dashboard`	Dashboard	Yes	`(dashboard)`	`app/src/app/(dashboard)/page.tsx`
5	`/nexus`	Nexus	Yes	`(dashboard)`	`app/src/app/(dashboard)/nexus/page.tsx`
6	`/nexus/upload`	Nexus	Yes	`(dashboard)`	`app/src/app/(dashboard)/nexus/upload/page.tsx`
7	`/nexus/documents`	Nexus	Yes	`(dashboard)`	`app/src/app/(dashboard)/nexus/documents/page.tsx`
8	`/nexus/documents/[docId]`	Nexus	Yes	`(dashboard)`	`app/src/app/(dashboard)/nexus/documents/[docId]/page.tsx`
9	`/zen`	Zen	Yes	`(dashboard)`	`app/src/app/(dashboard)/zen/page.tsx`
10	`/zen/chat/[sessionId]`	Zen	Yes	`(dashboard)`	`app/src/app/(dashboard)/zen/chat/[sessionId]/page.tsx`
11	`/profile`	Zen (users)	Yes	`(dashboard)`	`app/src/app/(dashboard)/profile/page.tsx`

graph LR
    Root["/"]:::primary -->|Unauthenticated| Login["/login"]:::primary
    Root -->|Authenticated| Dashboard["/dashboard"]:::primary
    Login -->|Success| Dashboard
    Login -->|"New user"| Register["/register"]:::primary
    Register -->|Success| Login
    Dashboard -->|"Launch Nexus"| Nexus["/nexus"]:::secondary
    Dashboard -->|"Launch Zen"| Zen["/zen"]:::secondary
    Nexus --> Upload["/nexus/upload"]:::neutral
    Nexus --> DocList["/nexus/documents"]:::neutral
    DocList --> DocDetail["/nexus/documents/[docId]"]:::neutral
    Zen --> Chat["/zen/chat/[sessionId]"]:::neutral

    classDef primary fill:#dbeafe,stroke:#3b82f6,color:#1e293b
    classDef secondary fill:#e0e7ff,stroke:#6366f1,color:#1e293b
    classDef success fill:#d1fae5,stroke:#10b981,color:#1e293b
    classDef warning fill:#fef3c7,stroke:#f59e0b,color:#1e293b
    classDef danger fill:#fee2e2,stroke:#ef4444,color:#1e293b
    classDef neutral fill:#f1f5f9,stroke:#64748b,color:#1e293b
    classDef highlight fill:#fae8ff,stroke:#a855f7,color:#1e293b
    classDef dark fill:#1e293b,stroke:#334155,color:#f8fafc

User Journey – Document Processing

This diagram shows the typical path a user follows when uploading and reviewing a financial document through Nexus.

graph TD
    Start["Login"]:::primary --> Dash["Dashboard"]:::primary
    Dash --> NexusOv["Nexus Overview<br/>Document stats"]:::secondary
    NexusOv --> Upload["Upload Page<br/>Drag and drop PDF"]:::secondary
    Upload --> Processing["Processing<br/>10-stage pipeline"]:::highlight
    Processing --> DocList["Documents List<br/>Find your document"]:::secondary
    DocList --> Detail["Document Detail<br/>5-tab view"]:::secondary
    Detail --> Pipeline["Pipeline Tab<br/>Stage timeline"]:::success
    Detail --> Data["Data Tab<br/>Securities table"]:::success
    Detail --> Export["Export Tab<br/>Download Excel"]:::success

    classDef primary fill:#dbeafe,stroke:#3b82f6,color:#1e293b
    classDef secondary fill:#e0e7ff,stroke:#6366f1,color:#1e293b
    classDef success fill:#d1fae5,stroke:#10b981,color:#1e293b
    classDef warning fill:#fef3c7,stroke:#f59e0b,color:#1e293b
    classDef danger fill:#fee2e2,stroke:#ef4444,color:#1e293b
    classDef neutral fill:#f1f5f9,stroke:#64748b,color:#1e293b
    classDef highlight fill:#fae8ff,stroke:#a855f7,color:#1e293b
    classDef dark fill:#1e293b,stroke:#334155,color:#f8fafc

User Journey – AI Chat

This diagram shows the typical path a user follows when interacting with Zen, including suggested queries and RAG-powered document Q&A.

graph TD
    Start2["Login"]:::primary --> Dash2["Dashboard"]:::primary
    Dash2 --> ZenLand["Zen Landing<br/>Choose a query"]:::secondary
    ZenLand --> NewChat["New Chat Session"]:::secondary
    NewChat --> Ask["Type Question"]:::highlight
    Ask --> Response["AI Response<br/>Markdown rendered"]:::success
    Response --> More["Ask Follow-up"]:::highlight
    More --> Response
    ZenLand --> Suggested["Click Suggested Query"]:::neutral
    Suggested --> NewChat
    NewChat --> UploadDoc["Upload Document"]:::highlight
    UploadDoc --> RAG["Ask About Document<br/>RAG-powered"]:::highlight
    RAG --> Response

    classDef primary fill:#dbeafe,stroke:#3b82f6,color:#1e293b
    classDef secondary fill:#e0e7ff,stroke:#6366f1,color:#1e293b
    classDef success fill:#d1fae5,stroke:#10b981,color:#1e293b
    classDef warning fill:#fef3c7,stroke:#f59e0b,color:#1e293b
    classDef danger fill:#fee2e2,stroke:#ef4444,color:#1e293b
    classDef neutral fill:#f1f5f9,stroke:#64748b,color:#1e293b
    classDef highlight fill:#fae8ff,stroke:#a855f7,color:#1e293b
    classDef dark fill:#1e293b,stroke:#334155,color:#f8fafc

Screen Details

1. Root (`/`)

Auth: Required – redirects unauthenticated users to /login, authenticated users see the home page.

Key UI elements:

Sentinel logo with animation
Two service launcher cards: Nexus (Document Intelligence) and Zen (Financial Chatbot AI)
Gradient background with Framer Motion stagger animations

API calls: None (client-side redirect only, reads isAuthenticated from auth-store).

Navigation destinations: /login (if unauthenticated), /nexus, /zen

Root page

2. Login (`/login`)

Auth: Not required. Redirects to /dashboard on successful login.

Key UI elements:

Email and password form fields with Zod validation
“Remember me” checkbox
Password visibility toggle
Link to registration page
Sentinel branding with feature highlights (BarChart3, Shield, FileText, Bot icons)
Error toast on failed login; expired-session banner when redirected with ?expired=true

API calls:

POST /api/v1/auth/login via loginAction server action

Navigation destinations: /dashboard (on success), /register (new user link)

3. Register (`/register`)

Auth: Not required. Redirects to /login on successful registration.

Key UI elements:

Username, email, password, confirm password form fields
Role selector (viewer, analyst, admin)
Team selector (INTERNAL, EXTERNAL)
Zod schema validation with real-time error messages
Link back to login page

API calls:

POST /api/v1/auth/register via registerAction server action

Navigation destinations: /login (on success or via link)

4. Dashboard (`/dashboard`)

Auth: Required. Mounted inside the (dashboard) layout with full app shell.

Key UI elements:

Personalised greeting with user’s first name and current date
3D Sentinel hologram (Three.js, hidden on mobile and neon theme)
Five platform metric cards: Documents, Extracted, Processing, Success Rate, AI Chats (with animated counters)
Two service launcher cards (Nexus, Zen) with live health indicators (green/red dots)
Recent activity feed (last 10 items from all services)
Client type tags (Wealth Managers, Family Offices, Private Equity, AIF Funds)

API calls:

GET /api/v1/dashboard?period=all_time via getDashboardData() (TanStack Query, 60s stale time)

Navigation destinations: /nexus, /zen

Dashboard

5. Nexus Overview (`/nexus`)

Auth: Required.

Key UI elements:

KPI cards: total documents, completed extractions, processing count, failed count, success rate
Recent documents table with status badges, confidence scores, product type tags
Quick action buttons: Upload Documents, View All Documents
Document type and product type filter pills

API calls:

GET /api/v1/nexus/documents/ via getDocuments() (document list)
GET /api/v1/dashboard?period=all_time via getDashboardData() (stats, shared query key)

Navigation destinations: /nexus/upload, /nexus/documents, /nexus/documents/[docId]

Nexus overview

6. Nexus Upload (`/nexus/upload`)

Auth: Required.

Key UI elements:

Drag-and-drop upload zone (react-dropzone) accepting PDF files
Product type selector (PMS, AIF, MF)
Optional password field for encrypted PDFs
File list with individual progress bars and status indicators
Upload and Process button (triggers V2 async pipeline)
Per-file status: pending, uploading, processing, complete, error

API calls:

POST /api/v1/nexus/upload/ via uploadDocument() (multipart file upload)
POST /api/v2/nexus/pipeline/process via processDocument() (start processing)
GET /api/v2/nexus/status/process/{process_id}/progress via getProcessProgress() (polling)

Navigation destinations: /nexus/documents (after successful upload)

Upload page

7. Nexus Documents List (`/nexus/documents`)

Auth: Required.

Key UI elements:

Paginated document table with sortable columns
Status badges (pending, processing, success, failed, needs_review)
Confidence score display with colour coding (high/medium/low)
Product type and document type tags
Bulk actions: delete, reprocess
Filter controls: status, product type, needs review toggle
Empty state illustration when no documents exist

API calls:

GET /api/v1/nexus/documents/ via getDocuments() (paginated, filtered)

Navigation destinations: /nexus/documents/[docId], /nexus/upload

Documents list

8. Nexus Document Detail (`/nexus/documents/[docId]`)

Auth: Required.

Key UI elements:

Split-pane layout: PDF viewer (left) and extraction data (right)
Original PDF rendering via pre-signed S3 URL
Layout annotation overlays (toggleable)
Extraction data table with field-level confidence scores
Token usage card showing LLM token consumption
Export controls: Excel download (standard and custom), JSON preview
PDF-to-data linking: clicking a table row highlights the corresponding PDF region

API calls:

GET /api/v1/nexus/documents/{doc_id} via getDocument() (document metadata)
GET /api/v1/nexus/documents/{doc_id}/extraction via getDocumentExtraction() (extraction data)
GET /api/v1/nexus/doc-fetch/{job_id}?type=ORIGINAL via getDocumentPdfUrl() (S3 pre-signed URL)
GET /api/v1/nexus/doc-fetch/{job_id}?type=LAYOUT via getDocumentLayoutImages() (annotated pages)
GET /api/v1/nexus/token-usage/{doc_id} via getTokenUsage() (LLM token consumption)

Navigation destinations: /nexus/documents (back), /nexus/upload (re-upload)

Document detail

9. Zen Landing (`/zen`)

Auth: Required.

Key UI elements:

Sentinel logo centred on page
“Start a new conversation” button
Suggested query categories: Market Intelligence (web search), Portfolio Analysis (RAG)
Pre-built query chips that launch a new session with a pre-filled prompt
Session history sidebar (collapsible) listing previous chat sessions
Web search toggle (on by default)

API calls:

GET /api/v1/zen/chat/ via getChatSessions() (session list)
POST /api/v1/zen/chat/ via createChatSession() (create new session)

Navigation destinations: /zen/chat/[sessionId] (on new chat or selecting existing session)

Zen landing

10. Zen Chat (`/zen/chat/[sessionId]`)

Auth: Required.

Key UI elements:

Full-height chat interface with message history
User and assistant message bubbles with markdown rendering (react-markdown + remark-gfm)
Typing indicator during assistant response
Message input with file attachment support (images, documents)
Web search toggle in input toolbar
Session sidebar with rename and delete controls
Document context panel showing attached files for RAG
Non-streaming response mode: sends message, waits for full response

API calls:

GET /api/v1/zen/chat/{sessionId} via getChatSession() (session + messages)
POST /api/v1/zen/chat/invoke via sendMessage() (send message, multipart with agent_id)
GET /api/v1/zen/chat/{sessionId}/context via getSessionContext() (attached documents)
GET /api/v1/zen/agents/ via getAgents() (available agents)
POST /api/v1/zen/uploads/ via uploadFile() (file attachment)

Navigation destinations: /zen (back to landing), /zen/chat/[otherSessionId] (switch session)

Zen chat

11. Profile (`/profile`)

Auth: Required.

Key UI elements:

User avatar with initials fallback
Editable first name and last name fields
Avatar URL field
Read-only display: email, role badge, team badge
Save button with loading state and success confirmation
Premium card styling with theme-aware design

API calls:

PUT /api/v1/zen/users/me via updateUser() (update profile)

Navigation destinations: Back to previous page (via app shell navigation)

Layout Architecture

Root Layout (`app/src/app/layout.tsx`)

Provides global providers: ThemeProvider, QueryClientProvider, Toaster, UserHydration. Applies the base font and Tailwind CSS class.

Auth Layout (`app/src/app/(auth)/layout.tsx`)

Centred card layout with no navigation shell. Used by /login and /register. Provides a minimal branded experience.

Dashboard Layout (`app/src/app/(dashboard)/layout.tsx`)

Full application shell with:

AppNavShell – top header with breadcrumbs, user avatar dropdown, theme toggle
Sidebar navigation with service links (Dashboard, Nexus, Zen, Profile)
Content area with padding and max-width constraints

Nexus Layout (`app/src/app/(dashboard)/nexus/layout.tsx`)

Wraps all /nexus/* routes with Nexus-specific sub-navigation (Overview, Upload, Documents).

Zen Layout (`app/src/app/(dashboard)/zen/layout.tsx`)

Wraps all /zen/* routes with the chat sidebar component for session management.

Screenshot Reference

All screenshots are captured during Playwright E2E test runs and stored in the screenshots/ directory. The following table maps each screen to its primary screenshot:

Screen	Screenshot
Root (authenticated)	`e2e-17-route-home.png`
Login (form filled)	`e2e-04-login-form-filled.png`
Login (success)	`e2e-05-login-success.png`
Register	`e2e-01-register-page.png`
Dashboard	`e2e-06-dashboard.png`
Nexus overview	`e2e-17-route-nexus.png`
Nexus upload	`e2e-07-nexus-upload-page.png`
Nexus upload (files selected)	`e2e-08-nexus-files-selected.png`
Nexus documents list	`e2e-11-nexus-documents-list.png`
Nexus document detail	`e2e-17-route-nexus-documents.png`
Zen landing	`e2e-13-zen-landing.png`
Zen chat (response)	`e2e-15-zen-chat-1-response.png`
Zen chat (with sessions)	`e2e-16-zen-with-sessions.png`
Profile	`profile-neon.png`
Final state	`e2e-20-final-state.png`

Screens & Routes

Screens & Routes

Route Map

Navigation Flow

User Journey – Document Processing

User Journey – AI Chat

Screen Details

1. Root (/)

2. Login (/login)

3. Register (/register)

4. Dashboard (/dashboard)

5. Nexus Overview (/nexus)

6. Nexus Upload (/nexus/upload)

7. Nexus Documents List (/nexus/documents)

8. Nexus Document Detail (/nexus/documents/[docId])

9. Zen Landing (/zen)

10. Zen Chat (/zen/chat/[sessionId])

11. Profile (/profile)

Layout Architecture

Root Layout (app/src/app/layout.tsx)

Auth Layout (app/src/app/(auth)/layout.tsx)

Dashboard Layout (app/src/app/(dashboard)/layout.tsx)

Nexus Layout (app/src/app/(dashboard)/nexus/layout.tsx)

Zen Layout (app/src/app/(dashboard)/zen/layout.tsx)

Screenshot Reference

1. Root (`/`)

2. Login (`/login`)

3. Register (`/register`)

4. Dashboard (`/dashboard`)

5. Nexus Overview (`/nexus`)

6. Nexus Upload (`/nexus/upload`)

7. Nexus Documents List (`/nexus/documents`)

8. Nexus Document Detail (`/nexus/documents/[docId]`)

9. Zen Landing (`/zen`)

10. Zen Chat (`/zen/chat/[sessionId]`)

11. Profile (`/profile`)

Root Layout (`app/src/app/layout.tsx`)

Auth Layout (`app/src/app/(auth)/layout.tsx`)

Dashboard Layout (`app/src/app/(dashboard)/layout.tsx`)

Nexus Layout (`app/src/app/(dashboard)/nexus/layout.tsx`)

Zen Layout (`app/src/app/(dashboard)/zen/layout.tsx`)