🏗 Architecture Overview

This page provides a high-level overview of the technical architecture planned for the MEDICARD-HMS project.

---

🧱 Core Architecture

🎯 Guiding Principles

The core system is designed to be:

• Modular: Clearly separates concerns between frontend (UI), backend (logic/API), and database (persistence).
• Scalable: Uses robust, widely-supported technologies that can grow with demand.
• Maintainable: Emphasizes clean architecture via common design patterns (REST APIs, ORMs, Blueprints) and tooling (Git, virtual environments, migrations).
• Secure: Sensitive config values (e.g., secrets, DB credentials) are stored in environment variables. Authentication/authorization will follow industry best practices.

---

🧩 Core Components

MEDICARD-HMS follows a modern three-tier web application architecture:

1. 🖥 Frontend (Client-Side)

• Technology: React
• Purpose: Provides the interactive UI doctors and staff use in the browser. Handles rendering views, managing form inputs, and displaying real-time data.
• Structure: Lives in a dedicated /frontend directory. Managed via Node.js and npm for dependencies and scripts.
• Communication: Makes asynchronous HTTP requests (typically using axios or fetch) to backend REST API endpoints. It is fully decoupled from the database and backend internals.

2. ⚙️ Backend (Server-Side API)

• Technology: Python with the Flask microframework.

• Purpose: Acts as the core logic layer. Handles API requests, business rules, database interactions, and user authentication.

• Key Libraries:

  • Flask – Core framework for routing and handling requests.
  • Flask-SQLAlchemy – ORM layer that maps Python objects to database tables.
  • Flask-Migrate – Handles database schema evolution via Alembic.
  • python-dotenv – Loads sensitive config values from .env files.
  • psycopg2-binary – PostgreSQL driver for Python.
  • (Planned: Authentication with Flask-Login or Flask-JWT-Extended, forms via Flask-WTF, etc.)

• Project Structure (Planned):

  /backend
    ├── run.py             # Entry point: creates and runs the Flask app
    ├── extensions.py      # Centralized Flask extension registration
    ├── models/models.py   # All database models (e.g., User, Patient)
    ├── routes/            # Modular route handlers (Blueprints)
    ├── requirements.txt   # Python dependency list
    ├── venv/              # Python virtual environment
  

• API Design: RESTful style. Resources like Patient, User, Order are exposed via structured endpoints. Communication uses JSON with standard HTTP verbs (GET, POST, PUT, DELETE).

3. 🗄 Database (Persistent Storage)

• Technology: PostgreSQL
• Purpose: Reliable, relational storage for structured healthcare data (e.g., users, encounters, notes, results).
• Access Pattern: Interfaced only through the backend via Flask-SQLAlchemy. The frontend has no direct DB access.
• Schema Management: Models are defined in models/models.py. Schema changes are tracked and applied using Flask-Migrate via Alembic.

🔧 Supporting Tools & Practices

• Version Control: Git is used for version tracking. The project is hosted publicly on GitHub at irinkobela/MEDICARD-HMS for collaboration and transparency.
• Configuration Management: A .env file stores environment-specific secrets (e.g., database URLs, secret keys). These are excluded from version control and loaded using python-dotenv.

---

🚀 Planned Extensions

These features are part of the planned roadmap and will expand functionality and maintainability:

🛡️ Authentication & Authorization

• Implement role-based access control (e.g., admin, doctor, nurse).
• Use Flask-Login or Flask-JWT-Extended for secure sessions or token-based authentication.

📁 File Uploads / Media

• Support for uploading and managing patient scans or documents.
• Local or cloud-based storage options to be evaluated.

🧪 Testing & CI

• Unit testing using pytest or unittest.
• Setup for automated testing and continuous integration (CI) pipeline.

🌐 Deployment Strategy

• Initial deployment via platforms like Heroku, Render, or Docker-based self-hosting.
• CI/CD workflow using GitHub Actions or similar tools.

🧠 Frontend Enhancements

• React architecture: planned layout for components/, pages/, hooks/, etc.
• Consider global state management (e.g., Context API, Redux) for complex UI needs.
• Responsive design for mobile/tablet usage in clinical settings.

🌍 Internationalization (i18n)

• Support for English/Georgian interface.
• String localization strategy using i18n libraries (e.g., react-i18next).

🚨 Error Handling & Validation

• API-level validation using marshmallow or pydantic.
• Standardized error response format across all endpoints.

---

🧪 This architecture is evolving in parallel with the codebase. Contributions and feedback are welcome as we refine the design together.