System Architecture
Architecture Overview
HCG AI is built on a monolithic Node.js architecture using Express.js and PostgreSQL. The system is designed to handle sensitive medical data tracking with a focus on type safety and modular service integration.
The application follows a classic Client-Server-Database pattern:
- Frontend: A vanilla JavaScript single-page application (SPA) that interacts with the backend via RESTful APIs.
- Backend: Express.js server variants providing authentication, data persistence, and third-party integrations (OpenAI, SMTP).
- Persistence: PostgreSQL managed through Drizzle ORM for schema-driven data integrity.
Server Variants
The repository provides different server entry points depending on the deployment environment and development preferences.
1. Standalone Server (simple-app-server.js)
The primary entry point for production and quick-start environments. It is a self-contained Node.js script that handles:
- Static file serving.
- Session-based authentication using
connect-pg-simple. - Direct interaction with PostgreSQL via
@neondatabase/serverlessor standardpg. - SMTP configuration for transactional emails.
Usage:
node simple-app-server.js
2. TypeScript Backend (server/index.ts & server/routes.ts)
A more structured, type-safe implementation of the backend logic. It separates route definitions from the server configuration and uses the shared schema for end-to-end type safety.
- Internal Role: Used for modern development workflows and scalable architectural patterns.
- Key Files:
server/routes.ts: Centralizes API endpoint definitions.server/auth.ts: Handles session logic and password hashing.
Data Modeling & Schema
The application uses Drizzle ORM to manage the PostgreSQL schema. The source of truth for all data structures is located in shared/schema.ts.
Core Entities
| Table | Description |
| :--- | :--- |
| users | User profiles and hashed credentials. |
| hcg_entries | Tracks β-hCG levels, dates, and optional LMP/cycle data. |
| ultrasound_entries | Stores gestational age, sac measurements (GS/YS/CRL), and heart rate. |
| analysis_results | Generated insights and risk levels (LOW/MEDIUM/HIGH). |
| sessions | Server-side session storage for authenticated users. |
REST API Specification
The backend exposes a JSON API for data management and AI interaction.
Authentication Endpoints
POST /api/register
Creates a new user account.
- Input:
{ "email": "...", "password": "...", "firstName": "...", "lastName": "..." } - Output: User object (excluding password).
POST /api/login
Authenticates a user and establishes a session.
- Input:
{ "email": "...", "password": "..." } - Output: Success message and user profile.
Medical Data Endpoints
GET /api/hcg-entries
Retrieves all HCG test records for the authenticated user.
- Output:
Array<HcgEntry>
POST /api/hcg-entries
Submits a new HCG blood test result.
- Input:
{ "date": "YYYY-MM-DD", "hcgValue": 5000, "units": "mIU/mL", "notes": "Optional notes", "lmpDate": "YYYY-MM-DD" }
POST /api/ultrasound-entries
Submits ultrasound findings.
- Input: Supports measurements like
gsSize,ysSize,crlSize, andheartRate.
Third-Party Integrations
AI Chatbot (OpenAI)
The server acts as a proxy to the OpenAI API. It provides a chatbot interface that contextually assists users with first-trimester queries.
- Requirement:
OPENAI_API_KEYmust be set in the environment.
Email Service (SMTP)
The application includes a built-in mailer service for password resets and system notifications.
- Default Provider: Configured for Hostinger/Smtp.
- Configuration: Managed via
SMTP_PASSandsimple-app-server.jstransporter settings.
Security & Authentication
- Session Management: The system uses
express-sessionwith a PostgreSQL store (connect-pg-simple). This ensures that user sessions persist across server restarts. - Password Hashing: User passwords are encrypted using bcrypt with a salt factor of 12 before being stored in the database.
- Route Protection: API routes are protected by an
isAuthenticatedmiddleware that validates the sessionuserIdbefore granting access to private resources.