Quickstart

Overview

This guide will walk you through creating your first MediGuide account, logging in, adding medical records, and viewing your health dashboard. By the end, you’ll understand the complete user workflow.

Make sure you’ve completed the Installation guide before proceeding.

Step-by-Step Guide

Start the Application

Ensure both the backend and frontend servers are running:Terminal 1 - Backend:

node server.js

Terminal 2 - Frontend:

npm run dev

Navigate to http://localhost:5173 in your browser.

Create an Account

On the landing page, you’ll see the user registration form. Fill in your details:

Username: Choose a unique username
Email: Your email address
Password: Must be at least 6 characters

POST /api/users/signup
Content-Type: application/json

Request Body:

{
  "username": "john_doe",
  "email": "[email protected]",
  "password": "securePassword123"
}

Response (201 Created):

{
  "message": "Usuario registrado exitosamente",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 1,
  "username": "john_doe"
}

The JWT token expires after 7 days. Store it securely and include it in the Authorization header for all authenticated requests.

If you already have an account, use the login form:

API Endpoint: Log In

POST /api/users/login
Content-Type: application/json

Request Body:

{
  "username": "john_doe",
  "password": "securePassword123"
}

Response (200 OK):

{
  "message": "Inicio de sesión exitoso",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 1,
  "username": "john_doe"
}

The application automatically stores your authentication token and user information in the browser’s session state.

Add Your First Medical Record

Once logged in, you’ll see the health tracking dashboard. Fill in your medical vitals in the “CHEQUEO MEDICO” section:

Tracked Metrics

Glucose Level (mg/dl): 70-180 normal range
Blood Oxygen (%): 95-100% normal range
Blood Pressure Systolic (mmHg): Upper number
Blood Pressure Diastolic (mmHg): Lower number
Temperature (°C): 36.1-37.2°C normal range
Age (years)
Height (meters)
Weight (kilograms)
Respiratory Rate (breaths/min): 12-20 normal
Blood Type: A+, A-, B+, B-, AB+, AB-, O+, O-
Heart Rate (beats/min): 60-100 normal range

API Endpoint: Save Medical Record

POST /api/medical-info
Content-Type: application/json
Authorization: Bearer <your_jwt_token>

Request Body:

{
  "userId": 1,
  "glucose": 95,
  "oxygenBlood": 98,
  "bloodPressureSystolic": 120,
  "bloodPressureDiastolic": 80,
  "temperature": 36.6,
  "age": 28,
  "height": 1.75,
  "weight": 70,
  "respiratoryRate": 16,
  "bloodType": "O+",
  "heartRate": 72
}

Response (201 Created):

{
  "message": "Registro médico guardado",
  "id": 1
}

All medical records are validated using Zod schema validation before being stored in the database.

View Your Health Dashboard

After saving your medical record, the application automatically updates your health dashboard with your latest vitals.

API Endpoint: Get Latest Medical Record

GET /api/medical-info/latest?userId=1
Authorization: Bearer <your_jwt_token>

Response (200 OK):

{
  "id": 1,
  "user_id": 1,
  "glucose": "95",
  "oxygen_blood": "98",
  "blood_pressure_systolic": "120",
  "blood_pressure_diastolic": "80",
  "temperature": "36.6",
  "age": "28",
  "height": "1.75",
  "weight": "70",
  "respiratory_rate": "16",
  "blood_type": "O+",
  "heart_rate": "72",
  "created_at": "2026-03-06T12:00:00.000Z"
}

Users can only access their own medical records. Attempting to query another user’s data will return a 403 Forbidden error.

Authentication Flow

MediGuide uses JWT (JSON Web Tokens) for authentication. Here’s how it works:

1. Token Generation

When you sign up or log in, the server generates a JWT token:

server.js

const token = jwt.sign(
  { id: user.id, username: user.username },
  process.env.JWT_SECRET,
  { expiresIn: '7d' }
);

2. Token Verification

All protected routes verify the token using middleware:

middleware/auth.js

const auth = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'No autorizado: token requerido' });
  }
  
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch {
    return res.status(401).json({ error: 'Token inválido o expirado' });
  }
};

3. Making Authenticated Requests

Include the token in the Authorization header:

const response = await fetch(`${API_URL}/api/medical-info`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(medicalData)
});

Data Validation

MediGuide uses Zod for runtime type checking and validation:

validators/medical.js

import { z } from 'zod';

const toNumber = z.union([z.number(), z.string()]).transform(val => Number(val));

export const medicalSchema = z.object({
  userId: toNumber,
  glucose: toNumber,
  oxygenBlood: toNumber,
  bloodPressureSystolic: toNumber,
  bloodPressureDiastolic: toNumber,
  temperature: toNumber,
  age: toNumber,
  height: toNumber,
  weight: toNumber,
  respiratoryRate: toNumber,
  bloodType: z.enum(['A+','A-','B+','B-','AB+','AB-','O+','O-']),
  heartRate: toNumber,
});

If validation fails, the API returns detailed error messages:

{
  "error": "Datos médicos inválidos",
  "detalles": {
    "glucose": ["Expected number, received string"],
    "bloodType": ["Invalid enum value"]
  }
}

Password Recovery

Forgot your password? MediGuide includes a password recovery flow:

Request Reset Code

POST /api/users/forgot-password
Content-Type: application/json

{
  "email": "[email protected]"
}

A 6-digit reset code is generated and stored in the database (valid for 30 minutes).

Verify Reset Code

POST /api/users/verify-reset-code
Content-Type: application/json

{
  "email": "[email protected]",
  "resetCode": "123456"
}

Reset Password

POST /api/users/reset-password
Content-Type: application/json

{
  "email": "[email protected]",
  "resetCode": "123456",
  "newPassword": "newSecurePassword123"
}

In development mode, reset codes are logged to the console for testing purposes.

Frontend Integration

The React frontend uses custom hooks and context for state management:

Authentication Hook

utils/useAuth.js

import { useState, useEffect } from 'react';

export const useAuth = () => {
  const [user, setUser] = useState(null);
  
  const login = (userData) => {
    setUser(userData);
    sessionStorage.setItem('user', JSON.stringify(userData));
  };
  
  const logout = () => {
    setUser(null);
    sessionStorage.removeItem('user');
  };
  
  useEffect(() => {
    const storedUser = sessionStorage.getItem('user');
    if (storedUser) {
      setUser(JSON.parse(storedUser));
    }
  }, []);
  
  return { user, login, logout };
};

Application Structure

App.jsx

import { useAuth } from './utils/useAuth';

function App() {
  const { user, login, logout } = useAuth();
  
  if (!user) {
    return <UserInfo onAuthSuccess={login} />;
  }
  
  return (
    <div className='Background'>
      <Header username={user.username} onLogout={logout} />
      <CTA />
      <MedCheck userId={user.userId} token={user.token} />
      <Analize />
      <HealthPlan userId={user.userId} token={user.token} />
      <Footer />
    </div>
  );
}

Health Check Endpoint

Verify the server is running and database is connected:

curl http://localhost:3001/api/health

{
  "status": "ok",
  "time": {
    "now": "2026-03-06T15:30:00.000Z"
  }
}

Common API Errors

400 Bad Request

{
  "error": "Todos los campos son requeridos"
}

Solution: Ensure all required fields are included in your request.

401 Unauthorized

{
  "error": "No autorizado: token requerido"
}

Solution: Include a valid JWT token in the Authorization header.

403 Forbidden

{
  "error": "No autorizado para consultar datos de otro usuario"
}

Solution: You can only access your own medical records.

404 Not Found

{
  "error": "No se encontraron registros médicos"
}

Solution: Add a medical record first before trying to retrieve data.

500 Internal Server Error

{
  "error": "Error interno del servidor"
}

Solution: Check server logs for detailed error information.

Next Steps

Now that you’ve completed the quickstart:

Authentication API

Explore authentication endpoints

Mobile Development

Build MediGuide for Android

Database Setup

Learn about the database schema

Production Deployment

Deploy to production

Example: Complete User Flow

Here’s a complete example using cURL:

# 1. Create account
curl -X POST http://localhost:3001/api/users/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane_smith",
    "email": "[email protected]",
    "password": "secure123"
  }'

# Response: {"token": "eyJ...", "userId": 2, "username": "jane_smith"}

# 2. Save medical record (use token from step 1)
curl -X POST http://localhost:3001/api/medical-info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ..." \
  -d '{
    "userId": 2,
    "glucose": 88,
    "oxygenBlood": 99,
    "bloodPressureSystolic": 118,
    "bloodPressureDiastolic": 78,
    "temperature": 36.5,
    "age": 32,
    "height": 1.68,
    "weight": 65,
    "respiratoryRate": 14,
    "bloodType": "A+",
    "heartRate": 68
  }'

# 3. Retrieve latest record
curl -X GET "http://localhost:3001/api/medical-info/latest?userId=2" \
  -H "Authorization: Bearer eyJ..."

Replace eyJ... with your actual JWT token received from the signup/login response.

Congratulations!

You’ve successfully set up MediGuide and learned the complete workflow from account creation to health tracking. You’re now ready to build and extend MediGuide for your specific needs.

Get Started

Core Features

Mobile App

Deployment

Overview

Step-by-Step Guide

API Endpoint: Log In

Tracked Metrics

API Endpoint: Save Medical Record

API Endpoint: Get Latest Medical Record

Authentication Flow

1. Token Generation

2. Token Verification

3. Making Authenticated Requests

Data Validation

Password Recovery

Frontend Integration

Authentication Hook

Application Structure

Health Check Endpoint

Common API Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Next Steps

Authentication API

Mobile Development

Database Setup

Production Deployment

Example: Complete User Flow

Congratulations!

Build docs developers (and LLMs) love

Get Started

Core Features

Mobile App

Deployment

​Overview

​Step-by-Step Guide

​API Endpoint: Sign Up

​API Endpoint: Log In

​Tracked Metrics

​API Endpoint: Save Medical Record

​API Endpoint: Get Latest Medical Record

​Authentication Flow

​1. Token Generation

​2. Token Verification

​3. Making Authenticated Requests

​Data Validation

​Password Recovery

​Frontend Integration

​Authentication Hook

​Application Structure

​Health Check Endpoint

​Common API Errors

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Next Steps

Authentication API

Mobile Development

Database Setup

Production Deployment

​Example: Complete User Flow

​Congratulations!

Build docs developers (and LLMs) love

Overview

Step-by-Step Guide

API Endpoint: Sign Up

API Endpoint: Log In

Tracked Metrics

API Endpoint: Save Medical Record

API Endpoint: Get Latest Medical Record

Authentication Flow

1. Token Generation

2. Token Verification

3. Making Authenticated Requests

Data Validation

Password Recovery

Frontend Integration

Authentication Hook

Application Structure

Health Check Endpoint

Common API Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Next Steps

Example: Complete User Flow

Congratulations!