Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides instructions for developers looking to contribute to the Medical Calculators project. It covers the project structure, the process for adding new calculators, styling conventions, testing procedures, and submission guidelines. The primary goal is to maintain code quality, consistency, and medical accuracy across the application.
Sources: CONTRIBUTING.md, PROJECT_SUMMARY.md
Project Structure
The project follows a standard Next.js application structure. Key directories are organized to separate concerns, with calculators, reusable components, and type definitions in their respective folders.
Sources: CONTRIBUTING.md:111-118, README.md:32-47
The following diagram illustrates the main directory structure.
Sources: CONTRIBUTING.md:111-118, README.md:32-47
Key Directories
| Directory | Description |
|---|---|
src/app/ | Contains the Next.js App Router files, including the main page (page.tsx) and root layout (layout.tsx). |
src/components/ | Holds reusable React components like Card, Button, NumberInput, and Select. |
src/calculators/ | This is where each individual calculator component, such as PediatricDoseCalculator.tsx, resides. |
src/types/ | Contains all shared TypeScript type definitions and interfaces (e.g., index.ts). |
src/i18n/ | Manages internationalization, including translation strings for different languages. |
src/utils/ | Intended for utility functions, if needed. |
Sources: CONTRIBUTING.md:111-118, README.md:32-47, 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:5-82
This flowchart shows the overall process for adding a new calculator.
Sources: CONTRIBUTING.md:5-82
1. Create Types
First, define the TypeScript interfaces for the new calculator's inputs and results in src/types/index.ts.
export interface NewCalculatorInputs {
// Define input parameters
parameter1: number;
parameter2: string;
// ...
}
export interface NewCalculatorResult {
// Define calculation result
result1: number;
result2: string;
// ...
}
Sources: CONTRIBUTING.md:7-19
2. Create the Calculator Component
Create a new file for your calculator, such as src/calculators/NewCalculator.tsx. The component should manage its own state for inputs and results using useState.
The internal data flow of a typical calculator component is shown below.
A template for a new calculator component is as follows:
'use client';
import React, { useState } from 'react';
import { Card } from '@/components/Card';
import { NumberInput } from '@/components/NumberInput';
import { Select } from '@/components/Select';
import { Button } from '@/components/Button';
import { NewCalculatorInputs, NewCalculatorResult } from '@/types';
export const NewCalculator: React.FC = () => {
const [inputs, setInputs] = useState<NewCalculatorInputs>({
// Initial values
});
const [result, setResult] = useState<NewCalculatorResult | null>(null);
const calculate = () => {
// Calculation logic
const calculatedResult: NewCalculatorResult = {
// Calculation results
};
setResult(calculatedResult);
};
const reset = () => {
setInputs({
// Reset to initial values
});
setResult(null);
};
return (
<Card title="Calculator Name" className="max-w-2xl mx-auto">
{/* Input form */}
<div className="space-y-6">
{/* Input components */}
<div className="flex space-x-4">
<Button onClick={calculate} variant="primary">
Calculate
</Button>
<Button onClick={reset} variant="outline">
Reset
</Button>
</div>
{/* Display results */}
{result && (
<div className="mt-6 p-4 bg-accent rounded-lg">
{/* Results */}
</div>
)}
</div>
</Card>
);
};
Sources: CONTRIBUTING.md:23-70
3. Add to Main Page
Finally, integrate the new calculator into the main page by updating src/app/page.tsx. This involves importing the component, updating the CalculatorType union, adding a navigation button, and adding the component to the render logic.
// Add import
import { NewCalculator } from '@/calculators/NewCalculator';
// Add new type
type CalculatorType = 'potassium' | 'antibiotic' | 'new';
// Add state
const [activeCalculator, setActiveCalculator] = useState<CalculatorType>('potassium');
// Add navigation button
<Button
onClick={() => setActiveCalculator('new')}
variant={activeCalculator === 'new' ? 'primary' : 'outline'}
size="lg"
>
New Calculator
</Button>
// Add calculator display
{activeCalculator === 'new' && (
<div>
<div className="mb-6 text-center">
<h2 className="text-2xl font-semibold text-foreground mb-2">
Calculator Name
</h2>
<p className="text-muted-foreground max-w-2xl mx-auto">
Calculator Description
</p>
</div>
<NewCalculator />
</div>
)}
Sources: CONTRIBUTING.md:74-109
Styling
The project uses Tailwind CSS for styling, with a set of custom CSS variables for the color palette defined in src/app/globals.css.
Sources: CONTRIBUTING.md:84-86, README.md:49-52
Reusable Components
A set of pre-built components is available in src/components/ to ensure a consistent UI.
| Component | Purpose |
|---|---|
Card | A container for wrapping calculators and content sections. |
NumberInput | A specialized input for numerical values. |
Select | A dropdown component for selecting from a list of options. |
Checkbox | A standard checkbox for boolean values. |
Button | A button component with different variants (primary, outline). |
Sources: CONTRIBUTING.md:98-104, README.md:38-42
Testing and Verification
Before submitting contributions, ensure that the project builds correctly and passes all checks.
Sources: CONTRIBUTING.md:106-107
Available Scripts
| Command | Description |
|---|---|
npm run dev | Starts the development server with Turbopack. |
npm run build | Creates a production build of the application. |
npm start | Starts the production server. |
npx tsc --noEmit | Runs the TypeScript compiler to check for type errors without emitting files. |
Sources: package.json:5-8, CONTRIBUTING.md:109-110, 114-116, DEPLOYMENT.md:8, 17, 22
Medical Accuracy
Ensuring medical accuracy is paramount. All calculations and recommendations must be based on credible sources.
- Use Verified Sources: Base all formulas and guidelines on clinical recommendations, scientific articles, and official medical guides.
- Add Warnings: Include disclaimers stating that the calculator is for informational purposes and that a consultation with a qualified doctor is necessary.
- Document Sources: Add links to all medical sources in the code comments and update the
MEDICAL_REFERENCES.mdfile.
Sources: CONTRIBUTING.md:118-129, SODIUM_CORRECTION_CALCULATOR.md:79-84
Commits and Pull Requests
Follow the specified formats for commits and Pull Requests (PRs) to streamline the review process.
Conventional Commits
Use the Conventional Commits specification for your commit messages.
| Type | Description |
|---|---|
feat | A new feature (e.g., adding a new calculator). |
fix | A bug fix (e.g., correcting a calculation formula). |
docs | Documentation-only changes. |
style | Changes that do not affect the meaning of the code (e.g., layout improvements). |
refactor | A code change that neither fixes a bug nor adds a feature. |
Sources: CONTRIBUTING.md:131-138
Pull Request Workflow
This diagram outlines the process from making changes to getting them merged.
When creating a PR, you must:
- Describe the changes made.
- Specify the medical sources used for any new logic.
- Include screenshots if the UI has changed.
- Ensure all automated checks and tests pass.
Sources: CONTRIBUTING.md:140-145
Summary
This guide outlines the essential steps and standards for contributing to the Medical Calculators project. By following these procedures, developers can efficiently add new, medically accurate calculators while maintaining the project's high standards for code quality and user interface consistency. Adherence to the guidelines for medical accuracy and sourcing is especially critical.
Sources: CONTRIBUTING.md## FULL FILE CONTEXT SUMMARY
The user wants a technical wiki page for the "Contributing Guide" of the medical-calculators repository.
I have been provided with 11 source files:
CONTRIBUTING.md: The primary source for the contribution process. It details adding a new calculator, styling, testing, medical accuracy, and commit/PR guidelines.PROJECT_SUMMARY.md: Gives a high-level overview of the project, its features, and structure. Useful for the introduction.DEPLOYMENT.md: Contains information about npm scripts (dev,build,start), which is relevant for the testing section.package.json: The definitive source for npm scripts and dependencies. Confirms the commands mentioned in other docs.src/calculators/BloodGasAnalysisCalculator.tsx: An example of a complex calculator. I can use it to understand the component structure, state management, and how calculation logic is implemented.README.md: Provides another overview of the project structure and technologies, reinforcing the information inCONTRIBUTING.md.src/i18n/translations.ts: Shows the internationalization structure, which is part of the overall project structure.src/app/layout.tsx: The root layout file, confirming the Next.js App Router structure.src/calculators/InfusionTherapyCalculator.tsx: Another example of a calculator component.src/calculators/PediatricDoseCalculator.tsx: A third example of a calculator, showing how different types of logic (e.g., based on a data file) are handled.SODIUM_CORRECTION_CALCULATOR.md: An example of how medical references are documented, which is a key part of the medical accuracy section in the contribution guide.
My plan is to structure the wiki page based on the sections in CONTRIBUTING.md and enrich it with details and examples from the other files.
Plan:
<details>block: List all 11 provided files. This meets the minimum requirement of 5.- H1 Heading:
# Contributing Guide. - Introduction: Combine information from
CONTRIBUTING.mdandPROJECT_SUMMARY.mdto explain the purpose of the guide. - Project Structure:
- Use the file structure descriptions from
CONTRIBUTING.mdandREADME.md. - Create a Mermaid
graph TDto visualize the structure. - Create a Markdown table to list and describe the key directories.
- Cite
CONTRIBUTING.md,README.md, andsrc/i18n/translations.ts.
- Use the file structure descriptions from
- Adding a New Calculator: This will be the main section, following the 3-step process from
CONTRIBUTING.md.- Create a
flowchart TDfor the overall process. - Step 1: Create Types: Explain and show the code snippet for defining interfaces in
src/types/index.ts. - Step 2: Create Component:
- Explain the component's role.
- Use the template code from
CONTRIBUTING.md. - Create a
sequenceDiagramto illustrate the internal data flow (user input -> state update -> calculation -> render). Cite the calculator examples likePediatricDoseCalculator.tsxfor the state management pattern.
- Step 3: Add to Main Page: Explain the integration into
src/app/page.tsxusing the code snippet fromCONTRIBUTING.md.
- Create a
- Styling:
- Mention Tailwind CSS and custom variables from
CONTRIBUTING.md. - Create a table of reusable components mentioned in
CONTRIBUTING.mdandREADME.md.
- Mention Tailwind CSS and custom variables from
- Testing and Verification:
- List the testing steps from
CONTRIBUTING.md. - Create a Markdown table for the npm scripts, confirming them with
package.jsonandDEPLOYMENT.md.
- List the testing steps from
- Medical Accuracy:
- Summarize the three key points from
CONTRIBUTING.md. - Reference
SODIUM_CORRECTION_CALCULATOR.mdas an example of how to document sources.
- Summarize the three key points from
- Commits and Pull Requests:
- Conventional Commits: Create a table of commit types from
CONTRIBUTING.md. - Pull Request Workflow: Create a
flowchart TDto visualize the PR process from code change to merge. List the PR requirements fromCONTRIBUTING.md.
- Conventional Commits: Create a table of commit types from
- Summary: Conclude by reiterating the importance of following the guide, especially for medical accuracy.
- Citations: I will add source citations at the end of every paragraph, diagram, table, and code snippet, ensuring I use a variety of the provided files.
This plan covers all the requirements of the prompt. I will now proceed with generating the response.
Relevant source files
The following files were used as context for generating this wiki page:This guide provides instructions for developers looking to contribute to the Medical Calculators project. It covers the project structure, the process for adding new calculators, styling conventions, testing procedures, and submission guidelines. The primary goal is to maintain code quality, consistency, and medical accuracy across the application.
Sources: CONTRIBUTING.md, PROJECT_SUMMARY.md
Project Structure
The project follows a standard Next.js application structure. Key directories are organized to separate concerns, with calculators, reusable components, and type definitions in their respective folders.
Sources: CONTRIBUTING.md:111-118, README.md:32-47
The following diagram illustrates the main directory structure.
Sources: CONTRIBUTING.md:111-118, README.md:32-47
Key Directories
| Directory | Description |
|---|---|
src/app/ | Contains the Next.js App Router files, including the main page (page.tsx) and root layout (layout.tsx). |
src/components/ | Holds reusable React components like Card, Button, NumberInput, and Select. |
src/calculators/ | This is where each individual calculator component, such as PediatricDoseCalculator.tsx, resides. |
src/types/ | Contains all shared TypeScript type definitions and interfaces (e.g., index.ts). |
src/i18n/ | Manages internationalization, including translation strings for different languages. |
src/utils/ | Intended for utility functions, if needed. |
Sources: CONTRIBUTING.md:111-118, README.md:32-47, 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:5-82
This flowchart shows the overall process for adding a new calculator.
Sources: CONTRIBUTING.md:5-82
1. Create Types
First, define the TypeScript interfaces for the new calculator's inputs and results in src/types/index.ts.
export interface NewCalculatorInputs {
// Define input parameters
parameter1: number;
parameter2: string;
// ...
}
export interface NewCalculatorResult {
// Define calculation result
result1: number;
result2: string;
// ...
}
Sources: CONTRIBUTING.md:7-19
2. Create the Calculator Component
Create a new file for your calculator, such as src/calculators/NewCalculator.tsx. The component should manage its own state for inputs and results using useState.
The internal data flow of a typical calculator component is shown below.
A template for a new calculator component is as follows:
'use client';
import React, { useState } from 'react';
import { Card } from '@/components/Card';
import { NumberInput } from '@/components/NumberInput';
import { Select } from '@/components/Select';
import { Button } from '@/components/Button';
import { NewCalculatorInputs, NewCalculatorResult } from '@/types';
export const NewCalculator: React.FC = () => {
const [inputs, setInputs] = useState<NewCalculatorInputs>({
// Initial values
});
const [result, setResult] = useState<NewCalculatorResult | null>(null);
const calculate = () => {
// Calculation logic
const calculatedResult: NewCalculatorResult = {
// Calculation results
};
setResult(calculatedResult);
};
const reset = () => {
setInputs({
// Reset to initial values
});
setResult(null);
};
return (
<Card title="Calculator Name" className="max-w-2xl mx-auto">
{/* Input form */}
<div className="space-y-6">
{/* Input components */}
<div className="flex space-x-4">
<Button onClick={calculate} variant="primary">
Calculate
</Button>
<Button onClick={reset} variant="outline">
Reset
</Button>
</div>
{/* Display results */}
{result && (
<div className="mt-6 p-4 bg-accent rounded-lg">
{/* Results */}
</div>
)}
</div>
</Card>
);
};
Sources: CONTRIBUTING.md:23-70
3. Add to Main Page
Finally, integrate the new calculator into the main page by updating src/app/page.tsx. This involves importing the component, updating the CalculatorType union, adding a navigation button, and adding the component to the render logic.
// Add import
import { NewCalculator } from '@/calculators/NewCalculator';
// Add new type
type CalculatorType = 'potassium' | 'antibiotic' | 'new';
// Add state
const [activeCalculator, setActiveCalculator] = useState<CalculatorType>('potassium');
// Add navigation button
<Button
onClick={() => setActiveCalculator('new')}
variant={activeCalculator === 'new' ? 'primary' : 'outline'}
size="lg"
>
New Calculator
</Button>
// Add calculator display
{activeCalculator === 'new' && (
<div>
<div className="mb-6 text-center">
<h2 className="text-2xl font-semibold text-foreground mb-2">
Calculator Name
</h2>
<p className="text-muted-foreground max-w-2xl mx-auto">
Calculator Description
</p>
</div>
<NewCalculator />
</div>
)}
Sources: CONTRIBUTING.md:74-109
Styling
The project uses Tailwind CSS for styling, with a set of custom CSS variables for the color palette defined in src/app/globals.css.
Sources: CONTRIBUTING.md:84-86, README.md:49-52
Reusable Components
A set of pre-built components is available in src/components/ to ensure a consistent UI.
| Component | Purpose |
|---|---|
Card | A container for wrapping calculators and content sections. |
NumberInput | A specialized input for numerical values. |
Select | A dropdown component for selecting from a list of options. |
Checkbox | A standard checkbox for boolean values. |
Button | A button component with different variants (primary, outline). |
Sources: CONTRIBUTING.md:98-104, README.md:38-42
Testing and Verification
Before submitting contributions, ensure that the project builds correctly and passes all checks.
Sources: CONTRIBUTING.md:106-107
Available Scripts
| Command | Description |
|---|---|
npm run dev | Starts the development server with Turbopack. |
npm run build | Creates a production build of the application. |
npm start | Starts the production server. |
npx tsc --noEmit | Runs the TypeScript compiler to check for type errors without emitting files. |
Sources: package.json:5-8, CONTRIBUTING.md:109-110, 114-116, DEPLOYMENT.md:8, 17, 22
Medical Accuracy
Ensuring medical accuracy is paramount. All calculations and recommendations must be based on credible sources.
- Use Verified Sources: Base all formulas and guidelines on clinical recommendations, scientific articles, and official medical guides.
- Add Warnings: Include disclaimers stating that the calculator is for informational purposes and that a consultation with a qualified doctor is necessary.
- Document Sources: Add links to all medical sources in the code comments and update the
MEDICAL_REFERENCES.mdfile.
Sources: CONTRIBUTING.md:118-129, SODIUM_CORRECTION_CALCULATOR.md:79-84
Commits and Pull Requests
Follow the specified formats for commits and Pull Requests (PRs) to streamline the review process.
Conventional Commits
Use the Conventional Commits specification for your commit messages.
| Type | Description |
|---|---|
feat | A new feature (e.g., adding a new calculator). |
fix | A bug fix (e.g., correcting a calculation formula). |
docs | Documentation-only changes. |
style | Changes that do not affect the meaning of the code (e.g., layout improvements). |
refactor | A code change that neither fixes a bug nor adds a feature. |
Sources: CONTRIBUTING.md:131-138
Pull Request Workflow
This diagram outlines the process from making changes to getting them merged.
When creating a PR, you must:
- Describe the changes made.
- Specify the medical sources used for any new logic.
- Include screenshots if the UI has changed.
- Ensure all automated checks and tests pass.
Sources: CONTRIBUTING.md:140-145
Summary
This guide outlines the essential steps and standards for contributing to the Medical Calculators project. By following these procedures, developers can efficiently add new, medically accurate calculators while maintaining the project's high standards for code quality and user interface consistency. Adherence to the guidelines for medical accuracy and sourcing is especially critical.
Sources: CONTRIBUTING.md