Hakim - Patient-Doctor connectivity app end-to-end

-

Building Hakim: A Production-Ready Healthcare Application

A deep dive into the architecture, implementation, and journey of building a modern telemedicine platform.

Healthcare Technology Concept

Digital transformation in modern healthcare.

🚀 Open Source Code Repository

View the Full Source Code on GitHub ➔

1. Why Do We Need Healthcare Apps?

The healthcare sector is undergoing a massive digital transformation. Following the global shifts in recent years, telemedicine has evolved from a niche alternative to a primary care modality. Recent statistics show that physician use of telemedicine surged from 15% to nearly 87%.

Patient portals and mobile health apps act as a central hub for health data, enabling 24/7 access to medical records, remote appointments, and secure communication. Studies indicate that 90% of patients rate their telemedicine experience as highly satisfactory.

  • Clinical Outcomes: Increased digital engagement directly correlates with better medication adherence and monitoring of chronic conditions.
  • Operational Efficiency: For providers, apps like Hakim reduce administrative burdens through self-service scheduling and billing, allowing staff to focus on direct patient care.
  • Accessibility: Telemedicine drastically reduces wait times and breaks down geographical barriers for remote patients.

2. Hakim App Walkthrough

Hakim is designed with three distinct user roles, ensuring secure, role-based access to the platform's features. Here is a walkthrough of the core functionalities:

Patient Dashboard Screen

The Hakim Patient Dashboard featuring upcoming appointments and quick actions.

👤 The Patient Portal

  • Smart Booking: Patients can search for doctors by specialization, view real-time availability, and book appointments instantly.
  • Medical Records vault: A secure area to view past diagnoses, lab reports, and download digital prescriptions.
  • Real-time Notifications: Powered by WebSockets, patients receive instant alerts for appointment approvals or changes.
Doctor Dashboard Screen

The Doctor Dashboard displaying the daily queue and vital statistics.

👨⚕️ The Doctor Dashboard

  • Schedule Management: Doctors can block out unavailability and set custom working hours.
  • Consultation Screen: A comprehensive view of the patient's medical history right beside the active consultation notes area.

🛡️ The Admin Panel

  • System Analytics: High-level view of platform usage, appointment volumes, and active doctors.
  • Audit Logs: Comprehensive security tracking for compliance and user management.

3. Detailed Implementation Techniques

Hakim was built using a robust, decoupled architecture separating the Flutter mobile/web client from the Node.js backend.

📱 Frontend: Flutter & Clean Architecture

The frontend abandons monolithic design in favor of strict separation of concerns utilizing the lib/core/ and lib/features/ pattern.

  • State Management (Riverpod 2.0): We utilize Riverpod's modern Notifier and NotifierProvider to manage complex states (like Authentication and Real-time Notifications). This provides compile-time safety and prevents memory leaks compared to traditional approaches.
  • Routing (GoRouter): A declarative routing system is implemented. An AuthWrapper acts as a middleware guard—if a JWT token isn't present in Secure Storage, the user is forcefully redirected to /login. Upon authentication, they are routed to /patient, /doctor, or /admin based on their decoded JWT role.
  • Networking (Dio): API requests are handled by a custom Dio client featuring request interceptors. It automatically injects the Bearer Token and intercepts 401 Unauthorized errors to seamlessly attempt a token refresh in the background without interrupting the user.

⚙️ Backend: Node.js, Express & WebSockets

The backend is a high-performance REST API designed with security and real-time capabilities in mind.

  • Database (Sequelize ORM & SQLite): The relational data model includes interconnected tables for Users, Patients, Doctors, Appointments, and Medical_Records, ensuring strict data integrity.
  • Input Validation (Joi): Before any data touches the database, it passes through strict Joi schemas. For instance, dates must pass isoDate() validation, and passwords must meet complexity requirements. If validation fails, the API returns a structured HTTP 422 error detailing the exact field.
  • Real-time Comm (Socket.io): When an appointment is booked, the REST controller delegates a task to the Socket service, which pushes an instant notification event to the specific doctor's active client session.

4. The Engineering Journey: Overcoming Hurdles

Building this application was not without its challenges. Here are three major engineering hurdles we solved during development:

A. Bridging the Architecture Gap

Initially, the application was trapped in a massive 2,700-line main.dart mock file. This file bypassed our clean lib/features/ architecture entirely. The critical fix was replacing this monolith with a clean 33-line entry point that instantiated a ProviderScope and bootstrapped our GoRouter instance, finally connecting the UI to our real backend services.

B. Navigating Package Deprecations

During compilation, we hit severe errors because our auth_provider.dart was using Riverpod's older StateNotifier pattern, which had breaking changes introduced in newer package versions. We executed a complete refactor of our global providers, migrating them to Riverpod's modern Notifier pattern, resolving the state mutation errors and future-proofing the app.

C. Advanced Error Surfacing

While testing the registration flow, the backend repeatedly threw 422 Validation Failed errors. Our frontend was swallowing the details, leaving the user with a generic "Registration Failed" message. We rewrote our Dio error interceptor inside auth_service.dart to traverse the JSON error tree, extract the specific Joi validation failure (e.g., "Date of birth must be a valid ISO date"), and present it natively to the user via a Flutter SnackBar.

Conclusion

Building the Hakim Healthcare app was a masterclass in migrating from a conceptual prototype to a production-ready, full-stack ecosystem. By enforcing clean architecture, resilient state management, and seamless backend integration, we've created a platform genuinely capable of handling the demands of modern telemedicine.

The future of healthcare is digital, and with Hakim, we are ready for it.

Comments

Post a Comment

Popular posts from this blog

Feel of Google's Antigravity

-
  Feel of  Google's Antigravity What is Antigravity ? The easiest way to understand it is to think of a highly capable manager coordinating a team of specialists. Imagine a cricket captain who has played with the same team for years. He knows exactly who to turn to in different situations because he understands every player's strengths, weaknesses, and style of play. He relies on that knowledge to put the right person in the right role at the right time. Now imagine an exceptionally intelligent captain. Suppose your team is defending 160 in a T20 match. The captain does not sit down and work everything out alone. He speaks with the senior-most bowler about the death overs, asks the wicketkeeper what they are noticing about the opposition batters, checks with the spinner about how much the pitch is turning, and may even consult the coach about field placements. Everyone contributes a piece of the puzzle. The captain listens, keeps track of what is happening on the field, and th...
Read more

Intelligent Video Generation Platform: Draft 1

-
Project Showcase Building an AI-Powered CBSE Educational Video Generator Combining the intelligence of the Gemini 2.5 Flash model with the beautiful visuals of Manim and FastAPI to create dynamic micro-lessons in under 3 minutes. View on GitHub The Vision: Educational Videos in Seconds Creating high-quality, engaging educational content for high school students is notoriously hard. Students are easily overwhelmed by abstract equations and dry textbook jargon. Standard slide decks are boring, and professional motion graphic animations require days of manual labor. To address this challenge, we built a fully automated CBSE Class 12 Storyboard Generator & Video Compiler . The workflow is simple: enter a CBSE curriculum topic (like Capacitors , DNA Replication , or Ma...
Read more

How to create your own CSV to Conversation Analyst using Python Pandas and a Language Model(here Gemini for demonstration)

-
Image
Staring at raw spreadsheets can be overwhelming and, let's be honest, a bit boring. But what if you could ask an AI to read your data files and explain them to you as if you were chatting over coffee? In this post, I'm going to show you exactly how to do that. We'll build a simple Python script that reads a dataset, crunches the basic math, and asks Google's Gemini AI to summarize it in plain English. I've also included the full code and a detailed PDF guide below! The Architecture: How It Works Think of this script as your personal digital analyst. Here is the step-by-step process of what's happening under the hood: Read the Data: It uses the pandas library to open a text or CSV file and formats it into a digital spreadsheet. Crunch the Numbers: It automatically grabs a snapshot of the data and calculates basic statistics (like the average, minimum, and maximum). Consult the AI: It feeds the raw data and mathematical results into a prom...
Read more