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/serverless or standard pg.
• 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, and heartRate.

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_KEY must 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_PASS and simple-app-server.js transporter settings.

Security & Authentication

• Session Management: The system uses express-session with 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 isAuthenticated middleware that validates the session userId before granting access to private resources.