System Architecture

High-Level Architecture

HCG AI is built on a modern, full-stack JavaScript architecture designed for high performance and type safety. It utilizes a hybrid Express.js and TypeScript backend, serving a lightweight Vanilla JS frontend. The system follows a monolithic structure to simplify deployment while maintaining clear separation between data persistence, business logic, and user interface.

Technology Stack

Backend

• Runtime: Node.js (v16+)
• Framework: Express.js
• Language: TypeScript (Primary) / JavaScript (Simple-server fallback)
• ORM: Drizzle ORM (for type-safe database queries)
• Authentication: Session-based via express-session and connect-pg-simple

Frontend

• Core: HTML5, CSS3, Vanilla JavaScript
• Visualization: Chart.js (for HCG trend tracking)
• Icons: Feather Icons
• Feedback/Support: Ybug integration

Database

• Engine: PostgreSQL
• Schema Management: Drizzle Kit

Data Modeling

The application utilizes a relational schema to manage users and clinical data. Below are the primary entities managed via the shared/schema.ts definition:

Core Entities

| Table | Purpose | | :--- | :--- | | users | Stores user profiles and hashed credentials. | | hcg_entries | Stores β-hCG blood test results, units, and notes. | | ultrasound_entries | Stores gestational measurements (GS, YS, CRL) and heart rate. | | analysis_results | Stores AI-generated risk levels (LOW, MEDIUM, HIGH) and clinical recommendations. | | sessions | Manages persistent user login states in the database. |

Authentication & Security

The system implements a secure, session-based authentication flow.

• Credential Handling: Passwords are encrypted using bcrypt (12 rounds) before storage.
• Session Management: Sessions are stored server-side in the PostgreSQL sessions table, ensuring users remain logged in across server restarts.
• Middleware: The requireAuth (or isAuthenticated) middleware protects sensitive API routes by verifying the userId in the session object.

API Reference (Public Interface)

The backend exposes a RESTful API for frontend consumption and potential third-party integration.

Authentication Endpoints

Register a New User

POST /api/register

• Body: { "email": "user@example.com", "password": "securepassword", "firstName": "Jane", "lastName": "Doe" }
• Success: Returns the created user object (excluding password).

User Login

POST /api/login

• Body: { "email": "user@example.com", "password": "securepassword" }
• Success: Sets a session cookie and returns user metadata.

Clinical Data Endpoints

All data endpoints require an active session cookie.

HCG Entries

• GET /api/hcg-entries: Fetches all test results for the authenticated user.
• POST /api/hcg-entries:
  • Input: { "date": "YYYY-MM-DD", "hcgValue": 500, "units": "mIU/mL", "notes": "Optional string" }
  • Output: The created entry object.

Ultrasound Entries

• GET /api/ultrasound-entries: Fetches all scan data.
• POST /api/ultrasound-entries:
  • Input: { "date": "YYYY-MM-DD", "gestationalAge": "6w2d", "crlSize": 5, "heartRate": 110 }

External Integrations

AI Chatbot (OpenAI)

The application integrates with the OpenAI API to provide conversational support for pregnancy-related queries. This is an internal service accessed via the frontend "AI Chat" tab.

• Configuration: Requires OPENAI_API_KEY in the .env file.

Email Service (SMTP)

Automated communications (such as password resets) are handled via a configured SMTP transporter.

• Default Provider: Hostinger (hello@in.hcgai.com).
• Configuration: Users can override this in simple-app-server.js using the SMTP_PASS environment variable.

File Organization

├── server/             # Express/TypeScript backend logic
│   ├── auth.ts         # Server-side auth utilities
│   ├── routes.ts       # Main API route definitions
│   └── storage.ts      # Database abstraction layer
├── shared/             # Shared TypeScript types and Drizzle schemas
├── index.html          # Main application entry point (Frontend)
├── auth.js             # Client-side authentication manager
├── simple-app-server.js# Alternative Node.js entry point for Neon/PostgreSQL
└── style.css           # Global application styles