Architecture Overview

**Referenced Files in This Document** - [README.md](file://README.md) - [package.json](file://package.json) - [docker-compose.yml](file://docker-compose.yml) - [server/index.ts](file://server/index.ts) - [server/routes.ts](file://server/routes.ts) - [server/db.ts](file://server/db.ts) - [server/lib/cassandra.ts](file://server/lib/cassandra.ts) - [server/lib/openai.ts](file://server/lib/openai.ts) - [server/lib/tesseract.ts](file://server/lib/tesseract.ts) - [server/chat-ws.ts](file://server/chat-ws.ts) - [server/messagepal/index.ts](file://server/messagepal/index.ts) - [server/storage.ts](file://server/storage.ts) - [shared/schema.ts](file://shared/schema.ts) - [client/src/App.tsx](file://client/src/App.tsx) - [client/src/lib/firebase.ts](file://client/src/lib/firebase.ts)

Introduction

This document presents the architecture of PersonalLearningPro, an AI-powered personalized learning platform. The system follows a layered clean architecture with clear separation between presentation, application, domain, and infrastructure concerns. It integrates a React frontend with an Express backend, multi-database persistence using MongoDB and Cassandra (via Astra DB), WebSocket real-time communication, and AI services (OpenAI and Tesseract). The document explains component roles, data flows, and operational patterns, and provides guidance on scalability, security, and deployment.

Project Structure

The repository is organized into three primary areas:

client: React application built with Vite, providing role-aware dashboards, chat UI, OCR scanning, analytics, and AI tutoring.
server: Express server hosting REST APIs, WebSocket servers, session management, and integrations with AI and databases.
shared: Validation schemas and shared types used by both client and server.

graph TB
subgraph "Client (React/Vite)"
FE_App["client/src/App.tsx"]
FE_Fire["client/src/lib/firebase.ts"]
end
subgraph "Server (Express)"
BE_Index["server/index.ts"]
BE_Routes["server/routes.ts"]
BE_WS_Chat["server/chat-ws.ts"]
BE_WS_MP["server/messagepal/index.ts"]
BE_DB["server/db.ts"]
BE_Cass["server/lib/cassandra.ts"]
BE_OpenAI["server/lib/openai.ts"]
BE_Tess["server/lib/tesseract.ts"]
BE_Store["server/storage.ts"]
end
subgraph "Shared"
SH_Schema["shared/schema.ts"]
end
FE_App --> BE_Routes
FE_Fire --> FE_App
BE_Index --> BE_Routes
BE_Index --> BE_WS_Chat
BE_Index --> BE_WS_MP
BE_Routes --> BE_Store
BE_Store --> BE_DB
BE_Store --> BE_Cass
BE_Routes --> BE_OpenAI
BE_Routes --> BE_Tess
BE_Routes --> SH_Schema

Diagram sources

server/index.ts
server/routes.ts
server/chat-ws.ts
server/messagepal/index.ts
server/db.ts
server/lib/cassandra.ts
server/lib/openai.ts
server/lib/tesseract.ts
server/storage.ts
shared/schema.ts
client/src/App.tsx
client/src/lib/firebase.ts

Section sources

README.md
package.json

Core Components

Presentation Layer (client):
- Role-aware routing and UI composition in App.tsx.
- Firebase integration for authentication and user profiles.
Application Layer (server):
- REST routes for user, test, question, attempt, answer, analytics, and chat/workspace/message management.
- WebSocket servers for real-time chat and MessagePal.
- Session middleware and logging.
Domain Layer (shared):
- Zod schemas for input validation and type safety across boundaries.
Infrastructure Layer (server):
- MongoDB connection and fallback storage.
- Cassandra/Astra DB client initialization and schema management.
- AI integrations (OpenAI, Tesseract).
- Storage abstraction coordinating MongoDB and Cassandra.

Section sources

client/src/App.tsx
client/src/lib/firebase.ts
server/routes.ts
server/chat-ws.ts
server/messagepal/index.ts
server/storage.ts
shared/schema.ts