Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for setting up, running, and contributing to the Medical Calculators project. The application is a web-based tool for healthcare professionals, built with Next.js, TypeScript, and Tailwind CSS. It features a modern, responsive, dark-themed interface for intuitive navigation and use.
The project includes several calculators, such as Potassium Correction, Antibiotic Prophylaxis, Pediatric Dosing, Blood Gas Analysis, and Infusion Therapy. This document covers the local development setup, project structure, and the process for adding new calculators.
Sources: README.md, PROJECT_SUMMARY.md, src/app/page.tsx
Project Setup
To get the project running on your local machine, you need to clone the repository and install the necessary dependencies.
Sources: DEPLOYMENT.md:3-15, README.md:18-25
Prerequisites
- Node.js
- npm (or a compatible package manager)
Installation and Local Development
Follow these steps to set up your development environment:
- Clone the repository:
git clone https://github.com/ziffmafiya/medical-calculators.git cd medical-calculators - Install dependencies:
npm install - Run the development server:
npm run dev - Open the application:
Navigate tohttp://localhost:3000in your web browser.
The local development workflow is illustrated below.
This diagram shows the sequence of commands to run the project locally.
Sources: DEPLOYMENT.md:3-15, README.md:18-25
Available Scripts
The package.json file defines several scripts for managing the application lifecycle.
| Script | Description |
|---|---|
dev | Starts the Next.js development server with Turbopack. |
build | Creates a production-ready build of the application. |
start | Starts the production server. |
lint | Runs ESLint to check for code quality issues. |
Sources: package.json:5-9
Project Structure
The project follows a standard Next.js App Router structure. Key directories are located within the src/ folder.
src/
├── app/ # Next.js App Router (pages, layout)
├── components/ # Reusable React components
├── calculators/ # Individual calculator components
├── types/ # TypeScript type definitions
├── i18n/ # Internationalization files
└── data/ # Medical data and references
Sources: README.md:29-43, CONTRIBUTING.md:104-110, PROJECT_SUMMARY.md:66-76
Directory Overview
| Directory | Purpose |
|---|---|
src/app | Contains the main application logic, including the root layout (layout.tsx) and the main page (page.tsx). |
src/components | Houses reusable UI components like Button, Card, NumberInput, and Select. |
src/calculators | Each file in this directory represents a specific medical calculator component. |
src/types | Defines shared TypeScript interfaces for calculator inputs and results. |
src/i18n | Manages translations for internationalization, with translations.ts defining text for multiple languages. |
Sources: README.md:29-43, CONTRIBUTING.md:104-110, src/i18n/translations.ts
Adding a New Calculator
The process for adding a new calculator involves creating types, building the component, and integrating it into the main application page.
Sources: CONTRIBUTING.md:3-85
Contribution Flow
The following diagram outlines the steps to add a new calculator.
This diagram illustrates the development workflow for introducing a new calculator.
1. Create Types
First, define the input and result interfaces for the new calculator in src/types/index.ts.
Example from CONTRIBUTING.md:
export interface NewCalculatorInputs {
parameter1: number;
parameter2: string;
}
export interface NewCalculatorResult {
result1: number;
result2: string;
}
Sources: CONTRIBUTING.md:6-16
2. Create the Calculator Component
Create a new React component file in src/calculators/. This component will manage its own state for inputs and results, and contain the calculation logic.
- Use the
useStatehook to manageinputsandresult. - Implement
calculateandresetfunctions. - Use pre-built UI components like
Card,NumberInput, andButton.
Sources: CONTRIBUTING.md:19-61
3. Integrate into the Main Page
Finally, update src/app/page.tsx to include the new calculator.
- Import the new calculator component.
- Update the
CalculatorTypetype to include a unique identifier for the new calculator. - Add a navigation button that sets the
activeCalculatorstate to the new calculator's identifier. - Conditionally render the new calculator component based on the
activeCalculatorstate.
Example from CONTRIBUTING.md and src/app/page.tsx:
// 1. Add import
import { NewCalculator } from '@/calculators/NewCalculator';
// 2. Add new type
type CalculatorType = 'electrolyte' | 'antibiotic' | 'pediatric' | 'new';
// In the component:
// 3. Add navigation button
<Button
onClick={() => setActiveCalculator('new')}
variant={activeCalculator === 'new' ? 'primary' : 'outline'}
>
New Calculator
</Button>
// 4. Add conditional rendering
{activeCalculator === 'new' && (
<div>
{/* ... title and description ... */}
<NewCalculator />
</div>
)}
Sources: CONTRIBUTING.md:64-85, src/app/page.tsx:10, 201-209
Deployment
The project is configured for easy deployment on platforms like Vercel.
Vercel Deployment
- Connect your Git repository to Vercel.
- Vercel will automatically detect the Next.js framework.
- The project will be built using
npm run buildand deployed.
The deployment flow is automated upon pushing changes to the connected Git branch.
This diagram shows the automated deployment process on Vercel.
Sources: DEPLOYMENT.md:23-33
Medical Accuracy and Contribution Guidelines
Contributors must ensure the medical accuracy of any new calculator.
- Use verified sources: All formulas and recommendations must be based on official clinical guidelines and scientific articles.
- Add warnings: Include disclaimers that the calculator is for informational purposes and does not replace a consultation with a qualified doctor.
- Document sources: Add links to medical references in the code and update
MEDICAL_REFERENCES.md. - Use Conventional Commits: Follow the conventional commit format (e.g.,
feat:,fix:,docs:).
Sources: CONTRIBUTING.md:92-118