Skip to content

Developer Guide

Jump to bottom
github-actions[bot] edited this page Feb 21, 2026 · 2 revisions

MediKeep Developer Documentation

Welcome to the MediKeep Developer Guide!

This comprehensive documentation will help you understand, develop, and contribute to the MediKeep medical records management system.

📚 Documentation Index

Getting Started

Document Description Time to Read
00. Quick Start Guide Set up local development environment in 10 minutes ⏱️ 10 min
05. Development Guide Code standards and best practices ⏱️ 20 min

Technical Documentation

Document Description Time to Read
01. Architecture Overview System design and architecture ⏱️ 20 min
02. API Reference Complete API documentation (95%+ coverage) ⏱️ 45 min
03. Database Schema Database design and tables ⏱️ 30 min
04. Deployment Guide Production deployment ⏱️ 40 min

🚀 Quick Navigation

I Want To...

→ Set up my development environment

→ Understand the architecture

→ Build API integrations

→ Work with the database

→ Deploy to production

→ Contribute code

🎯 By User Type

New Contributors (Start Here!)

  1. Quick Start Guide - Get your dev environment running with hot reload
  2. Architecture Overview - Understand the system design
  3. Development Guide - Learn code standards and workflow
  4. Pick a "good first issue" and start coding!

API Developers

  1. API Reference - Complete endpoint documentation
  2. Database Schema - Understand the data model
  3. Architecture Overview - Backend architecture
  4. Test your integrations using http://localhost:8000/docs

DevOps Engineers

  1. Deployment Guide - Production deployment
  2. Architecture Overview - Deployment architecture
  3. Docker Setup - Docker configuration
  4. Backup & Recovery - Disaster recovery

Frontend Developers

  1. Quick Start Guide - Setup frontend with npm start
  2. Architecture Overview - Frontend architecture
  3. API Reference - API integration
  4. Development Guide - Frontend code style

Database Administrators

  1. Database Schema - Complete schema reference (97% accuracy)
  2. Deployment Guide - Database setup
  3. Backup Strategy - Backup procedures
  4. Migration Guide - Schema migrations

📖 Documentation Health

Accuracy Status (Updated: February 2, 2026)

Document Accuracy Last Validated Status
00-quickstart.md 98% 2026-02-02 ✅ Excellent (Developer-focused)
01-architecture.md 98% 2026-02-02 ✅ Excellent
02-api-reference.md 95% 2026-02-02 ✅ Excellent (95%+ coverage)
03-database-schema.md 99% 2026-02-02 ✅ Outstanding
04-deployment.md 90% 2026-02-02 ✅ Good
05-contributing.md 100% 2026-02-02 ✅ Excellent

Overall Documentation Health: 97% ✅

All documentation has been validated against the actual codebase for accuracy.

Recent Improvements (February 2, 2026)

  • ✅ Full Documentation Audit: All docs validated against current codebase
  • ✅ Vite/Vitest Migration: Updated all references from CRA/Jest to Vite/Vitest
  • ✅ API Reference: Added Injuries, Notifications, and Admin sections (60+ new endpoints)
  • ✅ Database Schema: Added Symptom, Injury, and Notification system tables
  • ✅ Environment Variables: Updated all REACT_APP_ to VITE_ prefix

Previous Improvements (October 5, 2025)

  • ✅ Quick Start: Reordered for developers - local development setup first
  • ✅ API Reference: Expanded from 10% to 95%+ coverage (1,325 lines)
  • ✅ Database Schema: Validated all 31 tables against actual models
  • ✅ Development Guide: Simplified for solo developer workflow
  • ✅ All Corrections: Fixed medication fields, vitals fields, insurance paths

🛠️ Technology Stack

Backend

  • Language: Python 3.12+
  • Framework: FastAPI 0.115+
  • ORM: SQLAlchemy 2.0+
  • Database: PostgreSQL 15+
  • Migrations: Alembic
  • Authentication: JWT (python-jose) + SSO (Google, GitHub, OIDC)

Frontend

  • Language: JavaScript/JSX
  • Framework: React 18.3+
  • UI Library: Mantine UI 8.x
  • Build Tool: Vite 7.x
  • State Management: Context API + Custom Hooks
  • API Client: Axios
  • Testing: Vitest + React Testing Library

Infrastructure

  • Containerization: Docker & Docker Compose
  • Reverse Proxy: Nginx (optional)
  • Process Manager: Uvicorn
  • File Storage: Local filesystem (uploads/)
  • Integrations: Paperless-ngx (optional)

📋 Development Checklist

Before You Start

While Developing

  • Run backend with python run.py (auto-reload)
  • Run frontend with npm start (auto-refresh)
  • Write tests for new features
  • Update documentation if needed
  • NO console.log in production code
  • NO debug code before committing
  • Run pytest and npm test before PR

Before Submitting PR

  • All tests pass (pytest and npm test)
  • Code follows style guidelines
  • Documentation updated
  • No console.log or debug code
  • Migrations created if needed
  • Self-review completed

Before Deployment

🔗 External Resources

Official Documentation

Project Links

🤝 Getting Help

Documentation Issues

If you find errors in the documentation:

  1. Check existing documentation - issue might be known
  2. Open an issue on GitHub with label documentation
  3. Or submit a PR with the fix

Development Questions

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and general discussion
  • Code Review: Comment on relevant PRs

Common Issues

Problem Solution
Backend won't start See Troubleshooting
Database connection failed Check Database Issues
Frontend CORS errors Verify backend running on port 8000
Tests failing Check Testing Guide
Migration errors See Database Troubleshooting

📝 Contributing to Documentation

Documentation Standards

  • Clarity: Write for beginners
  • Accuracy: Validate against actual code
  • Examples: Include real code examples
  • Structure: Use consistent formatting
  • Updates: Keep in sync with code changes

How to Contribute

  1. Fork the repository
  2. Update documentation in docs/developer-guide/
  3. Test all examples to ensure accuracy
  4. Submit PR with clear description
  5. Request review from maintainers

Current Documentation Needs

Priority areas (most are now complete):

  • ✅ API Reference - Now 95%+ complete
  • ✅ Quick Start - Reordered for developers
  • ✅ Database Schema - Validated and accurate
  • ⚠️ Add more screenshots (optional)
  • ⚠️ Create video tutorials (optional)
  • ⚠️ Frontend component documentation (optional)

✨ Quick Tips

For New Contributors

Start with Quick Start - Option 1 for local development with hot reload.

For API Developers

The Swagger UI at http://localhost:8000/docs is your interactive API playground.

For DevOps

Always test backup/restore procedures before deploying to production.

For Frontend Devs

Check Contributing Guide for strict standards - NO console.log in production!

For Everyone

Use python run.py to start the backend - simplest way with auto-reload.

📊 Documentation Statistics

  • Total Documents: 8 (including README and Validation Report)
  • Total Lines: 8,283 lines
  • Total Size: 503 KB
  • Code Examples: 200+
  • API Endpoints Documented: 95%+ (284 endpoints)
  • Last Major Update: 2025-10-05
  • Overall Accuracy: 95%

🏆 Best Practices

Code Quality

  • Follow Contributing Guide guidelines strictly
  • Write tests for all new features
  • Use type hints (Python) and PropTypes (React)
  • NEVER log PHI or sensitive data
  • NO console.log in production code

Security

  • Validate all inputs (frontend AND backend)
  • Use parameterized queries (SQLAlchemy ORM)
  • Implement rate limiting on sensitive endpoints
  • Never commit secrets to git
  • Change default credentials in production

Performance

  • Add database indexes for foreign keys
  • Paginate all list endpoints (max 100 items)
  • Use React.memo for expensive components
  • Optimize database queries with proper joins

Development Workflow

  • Use python run.py for backend (auto-reload)
  • Use npm start for frontend (auto-refresh)
  • Run tests before committing
  • Update docs when code changes
  • Create migrations for database changes

📞 Contact

Maintainer: MediKeep Team Repository: github.com/afairgiant/MediKeep Issues: GitHub Issues Discussions: GitHub Discussions

Happy Developing! 🚀

Remember: Good documentation is just as important as good code. These docs are now 95% accurate and ready to help you contribute effectively!

🎯 Quick Start Commands

# Clone repository
git clone https://github.com/afairgiant/MediKeep.git
cd MediKeep

# Setup backend (in terminal 1)
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
alembic upgrade head
python run.py  # Backend running at http://localhost:8000

# Setup frontend (in terminal 2)
cd frontend
npm install
npm start  # Frontend running at http://localhost:3000

# Default login: admin / admin123

See Quick Start Guide for detailed instructions.

Documentation auto-synced from docs/ folder.

Edit on GitHub | Report Documentation Issue

Navigation

Welcome

Users

Administrators

Developers

Operations

Features

Resources

Clone this wiki locally