D2. Design Document
Explains the core ideas behind the code so a new developer can work with it confidently.
1: Architecture Diagram
2. Code Repository and README
2.1: Repository Information
Repository URL: https://github.com/ethanbonsall/Pediatric-Blue-Book
The complete source code is archived in this GitHub repository. It contains all application code, configuration files, tests, and documentation needed to build and deploy the system.
2.2: README: How to build the system
Tech Stack
- Framework: Next.js
- Language: TypeScript
- UI: React, Tailwind CSS, shadcn/ui
- Backend: Supabase
- Testing: Jest
- Deployment: Vercel
- Domain: Namecheap
Running the project locally
- Clone repository:
git clone https://github.com/ethanbonsall/Pediatric-Blue-Book.git
- Navigate to web directory:
cd pediatric-blue-book
cd web
- Install dependencies:
npm install --force
- Create
.env.localfile with Supabase keys inside /web - Run development server:
npm run dev
- The app will be available at
http://localhost:3000/
Testing
Tests are written with Jest and stored in __tests__/.
- Run tests:
npm test
- Watch mode:
npm test:watch
2.3: Module Structure
Module relationships
- pages/ (index.tsx, admin.tsx, profile.tsx) import components/ui/ to build page UI
- pages/_app.tsx wraps entire app, imports components/context/themecontext.tsx for global state
- components/ui/ components import components/lib/types.ts for TypeScript types
- All components use components/lib/supabase.tsx for database access
- components/ui/ use components/lib/utils.ts for helper functions
- app/api/delete-user/route.ts handles backend API logic
- __tests__/ test files import components and run Jest tests
- All .tsx/.ts files use TypeScript for type safety
- Styling uses Tailwind CSS (configured in tailwind.config.ts)
3. Detailed Data Definitions
Database Schema
Tables:users
Purpose: User profile information
| Column Name | Data Type | Description |
|---|---|---|
| created_at | Timestamp with timezone | Account creation timestamp |
| first_name | text | User's first name |
| text | User email address | |
| title | text | User title or position |
| id | UUID | Primary key, unique user identifier |
| role | text | User role or permissions |
Tables:nutrient needs
Purpose: Nutrient requirements for users
| Column Name | Data Type | Description |
|---|---|---|
| id | bigint | nutrient identifier |
| created_at | Timestamp with timezone | Timestamp of nutrient added |
| nutrient | text | Nutrient name |
| age_bottom | double precision | Minimum age for nutrient requirement |
| age_top | double precision | Maximum age for nutrient requirement |
| amount | double precision | required amount |
| measurement_type | text | Measurement type for nutrient amount |
| activity_level | text | Activity level for nutrient requirement |
| needs_type | text | Type of nutrient required |
| sex | text | Sex of patient |
Tables:ingredients
Purpose: recipe ingredients
The ingredient list for the formulas.
| Column Name | Data Type | Description |
|---|---|---|
| product | text | Product name |
| company_brand | text | Company or brand name |
| age | text | Age group |
| notes | text | any notes |
| id | uuid | id of the product |
| active | boolean | if active or not |
| approved | boolean | if approved or not |
| protein_sources | text | Sources of protein |
| carbohydrate_sources | text | Sources of carbohydrates |
| fat_sources | text | Sources of fat |
| prebiotic_sources | text | Sources of prebiotics |
| probiotic_sources | text | probiotic sources |
| specialty_ingredients | text | Specialty ingredients |
| grams_per_scoop | double precision | per scoop amount |
| grams_per_teaspoon | double precision | per teaspoon amount |
| grams_per_tablespoon | double precision | per tablespoon amount |
| grams_per_cup | double precision | per cup amount |
| calories_per_gram | double precision | calories per gram |
| np100_total_protein_g | double precision | total protein amount |
| np100_total_fat_g | double precision | total fat amount |
| np100_total_carbohydrate_g | double precision | total carbohydrate amount |
| np100_water_ml_standard | double precision | standard water amount in ml |
| np100_vitamin_a_mcg_re | double precision | total vit a amount |
| np100_vitamin_d_mcg | double precision | total vit d amount |
| np100_vitamin_e_mg | double precision | total vit e amount |
| np100_vitamin_k_mcg | double precision | total vit k amount |
| np100_thiamin_mg | double precision | total thiamin amount |
| np100_riboflavin_mg | double precision | total riboflavin amount |
| np100_niacin_mg | double precision | total niacin amount |
| np100_b6_mg | double precision | total b6 amount |
| np100_b12_mcg | double precision | total b12 amount |
| np100_vitamin_c_mg | double precision | total vitamin c amount |
| np100_folic_acid_mcg | double precision | total folic acid amount |
| np100_biotin_mcg | double precision | total biotin amount |
| np100_pantothenic_acid_mg | double precision | total pantothenic acid amount |
| np100_choline_mg | double precision | total choline amount |
| np100_inositol_mg | double precision | total inositol amount |
| np100_sodium_mg | double precision | total sodium amount |
| np100_potassium_mg | double precision | total potassium amount |
| np100_chloride_mg | double precision | total chloride amount |
| np100_calcium_mg | double precision | total calcium amount |
| np100_phosphorus_mg | double precision | total phosphorus amount |
| np100_iron_mg | double precision | total iron amount |
| np100_zinc_mg | double precision | total zinc amount |
| np100_magnesium_mg | double precision | total magnesium amount |
| np100_iodine_mcg | double precision | total iodine amount |
| np100_manganese_mg | double precision | total manganese amount |
| np100_selenium_mcg | double precision | total selenium amount |
| np100_chromium_mcg | double precision | total chromium amount |
| np100_molybdenum_mcg | double precision | total molybdenum amount |
| np100_copper_mg | double precision | total copper amount |
| probiotic | text | total probiotic amount |
| allergens | text | any allergens |
| displacement_ml_per_g | double precision | displacement amount |
| np100_standard_volume | double precision | volume of the fomula |
| npc_percent_free_water | numeric | percentage of water |
| npc_percent_cal_from_cho | numeric | percentage of calories from carbohydrates |
| npc_percent_cal_from_fat | numeric | percentage of calories from fat |
| npc_percent_cal_from_protein | numeric | percentage of calories from protein |
| np100_fluoride_mg | double precision | total fluoride amount |
| np100_fiber_g | double precision | total fiber amount |
4. Design Rationale
4.1: Technology choices
- TypeScript: compile-time type safety, better IDE support, clearer refactoring and documentation.
- Next.js: team familiarity, SSR/SSG for performance/SEO, built-in API routes, seamless Vercel deploys.
- Supabase: PostgreSQL (relational queries), row-level security for HIPAA, open-source/self-host option, SQL familiarity.
- Vercel: team experience, automatic SSL & CI/CD, Next.js-optimized, free tier for launch.
- Testing: Jest
- Tailwind CSS: fast development with utility classes, team expertise, small purged bundles and consistent design.
4.2: Architechture
Three-layer separation (Presentation / Business Logic / Data Access) for defense-in-depth, clearer code, and HIPAA-compliant data isolation.
4.3: Data model
Soft delete (is_active)to meet retention/audit requirements and allow restores.
JSONB for input/outputto support evolving calculation schemas without migrations and keep good performance.
Separate calculations tableto preserve immutable history, enable comparisons and auditing.
4.4: Dependencies (core)
Next.js ^14, React ^18, TypeScript ^5, Supabase Client ^2.38, Tailwind CSS ^3.3, Zod ^3.22, Jest ^29 — chosen for stability, team familiarity, and features needed for secure, testable medical calculations.