{"id":27376733,"url":"https://github.com/ras-pekt/appointment_scheduling_system","last_synced_at":"2026-04-14T06:04:33.721Z","repository":{"id":287585464,"uuid":"961866614","full_name":"Ras-Pekt/appointment_scheduling_system","owner":"Ras-Pekt","description":"A robust, secure backend service that efficiently manages patient data and enables seamless appointment scheduling with healthcare providers.","archived":false,"fork":false,"pushed_at":"2025-04-12T16:09:43.000Z","size":2934,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T17:25:50.693Z","etag":null,"topics":["celery","fastapi","mysql","redis"],"latest_commit_sha":null,"homepage":"https://appointmentschedulingsystem-production.up.railway.app/docs","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ras-Pekt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-07T09:37:02.000Z","updated_at":"2025-04-12T16:09:46.000Z","dependencies_parsed_at":"2025-04-12T17:36:14.871Z","dependency_job_id":null,"html_url":"https://github.com/Ras-Pekt/appointment_scheduling_system","commit_stats":null,"previous_names":["ras-pekt/appointment_scheduling_system"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ras-Pekt%2Fappointment_scheduling_system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ras-Pekt%2Fappointment_scheduling_system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ras-Pekt%2Fappointment_scheduling_system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ras-Pekt%2Fappointment_scheduling_system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ras-Pekt","download_url":"https://codeload.github.com/Ras-Pekt/appointment_scheduling_system/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717259,"owners_count":21150388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","fastapi","mysql","redis"],"created_at":"2025-04-13T12:53:24.518Z","updated_at":"2026-04-14T06:04:33.693Z","avatar_url":"https://github.com/Ras-Pekt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏥 Healthcare Appointment Scheduling System\n\nA secure and scalable backend system for managing patients, doctors, and healthcare appointments. This project leverages **FastAPI**, **MySQL**, and **Celery with Redis** for asynchronous processing to deliver a robust solution for real-world healthcare workflows.\n\n---\n\n## 🔧 Features\n\n- **Patient Management**: Register, view, and manage patient profiles with basic details and insurance information.\n- **Doctor Management**: Register and manage doctors with specializations and configurable availability schedules.\n- **Appointment Scheduling**: Book, list, and cancel appointments with real-time availability checks and conflict prevention.\n- **Medical Records**: Add and retrieve patient records linked to appointments with access control.\n- **Authentication \u0026 Authorization**: Role-based access control using OAuth2 + JWT.\n- **Async Email Notifications**: Background task processing using Celery + Redis.\n\n---\n\n## 🧱 Tech Stack\n\n| Layer    | Technology        |\n| -------- | ----------------- |\n| Backend  | FastAPI (Python)  |\n| Database | MySQL             |\n| Auth     | OAuth2 + JWT      |\n| Queue    | Celery with Redis |\n| Docs     | Swagger (OpenAPI) |\n\n---\n\n## 🚀 Getting Started\n\n### ✅ Prerequisites\n\n- Docker \u0026 Docker Compose\n\n---\n\n### 📦 Installation\n\n1. Clone the repo:\n\n```bash\ngit clone https://github.com/Ras-Pekt/appointment_scheduling_system.git\ncd appointment_scheduling_system\n```\n\n2. Create a `.env` file:\n\n```env\n# .env\nMYSQL_ROOT_PASSWORD=\u003cmysql_root_password\u003e\nMYSQL_USER=\u003capp_admin\u003e\nMYSQL_PASSWORD=\u003capp_admin_password\u003e\nMYSQL_DATABASE=\u003cmysql_db\u003e\nADMIN_EMAIL=\u003cadmin_email\u003e\nADMIN_PASSWORD=\u003cadmin_password\u003e\nEMAIL_ADDRESS=\u003cyour_email_address\u003e\nEMAIL_PASSWORD=\u003cyour_email_password\u003e\nSECRET_KEY=\u003csecret_key\u003e\n```\n\n### 🛠️ Environment Variables\n\n| Variable              | Description                                                                   |\n| --------------------- | ----------------------------------------------------------------------------- |\n| `MYSQL_ROOT_PASSWORD` | Password for the MySQL root user (used internally by the database container). |\n| `MYSQL_USER`          | Custom MySQL user for the app (used by the backend to connect to the DB).     |\n| `MYSQL_PASSWORD`      | Password for the above MySQL app user.                                        |\n| `MYSQL_DATABASE`      | Name of the database the app will use.                                        |\n| `ADMIN_EMAIL`         | Email address for the default admin account (created on first run).           |\n| `ADMIN_PASSWORD`      | Password for the default admin account.                                       |\n| `EMAIL_ADDRESS`       | Sender email address used for notifications (e.g. appointment confirmations). |\n| `EMAIL_PASSWORD`      | App-specific password or SMTP password for the sender email.                  |\n| `SECRET_KEY`          | Secret key for signing JWT tokens and other cryptographic operations.         |\n\n\u003e 📌 **Note:**  \n\u003e A default root admin account is created when the app is first initialized. This account is required to create additional admin users, as **only an admin can create other admin accounts**.\n\u003e\n\u003e - **Email:** Defined in the `ADMIN_EMAIL` environment variable\n\u003e - **Password:** Defined in the `ADMIN_PASSWORD` environment variable\n\u003e\n\u003e 💡 Additionally, to enable email functionality, refer to your email provider’s documentation on how to configure an **app-specific password**. This should be set in the `EMAIL_PASSWORD` variable.\n\n3. Run the app:\n\n```bash\ndocker-compose up --build\n```\n\n4. Access Swagger UI:\n\n```\nhttp://0.0.0.0:8000/docs\n```\n\n---\n\n## 📚 API Overview\n\n### 🔐 Auth\n\n| Endpoint      | Method | Description             | Access |\n| ------------- | ------ | ----------------------- | ------ |\n| `/auth/login` | POST   | Obtain JWT access token | Public |\n\n---\n\n### 👤 Users (Admin Only)\n\n| Endpoint                       | Method | Description              |\n| ------------------------------ | ------ | ------------------------ |\n| `/users/all-users`             | GET    | List all users           |\n| `/users/user/{user_id}`        | GET    | Retrieve a specific user |\n| `/users/register-new-admin`    | POST   | Register a new admin     |\n| `/users/register-new-doctor`   | POST   | Register a new doctor    |\n| `/users/register-new-patient`  | POST   | Register a new patient   |\n| `/users/delete-user/{user_id}` | DELETE | Delete a user by ID      |\n\n---\n\n### 👨‍⚕️ Doctors\n\n| Endpoint                                              | Method | Description                                       | Access      |\n| ----------------------------------------------------- | ------ | ------------------------------------------------- | ----------- |\n| `/doctors/me`                                         | GET    | Get the logged-in doctor's profile                | Doctor Only |\n| `/doctors/all-doctors`                                | GET    | List all doctors (optional specialization filter) | Public      |\n| `/doctors/appointments`                               | GET    | Get all appointments for logged-in doctor         | Doctor Only |\n| `/doctors/new-availability-slot`                      | POST   | Add new availability slots                        | Doctor Only |\n| `/doctors/availability/change-availability/{slot_id}` | PATCH  | Change availability slot status                   | Doctor Only |\n| `/doctors/availability/delete-availability/{slot_id}` | DELETE | Delete availability slot                          | Doctor Only |\n| `/doctors/new-medical-report/{appointment_id}`        | POST   | Create a new medical record                       | Doctor Only |\n| `/doctors/medical-records`                            | GET    | List all medical records created by doctor        | Doctor Only |\n| `/doctors/medical-records/{patient_id}`               | GET    | Get records for a specific patient                | Doctor Only |\n\n---\n\n### 🧑‍⚕️ Patients\n\n| Endpoint                                    | Method | Description                                     | Access       |\n| ------------------------------------------- | ------ | ----------------------------------------------- | ------------ |\n| `/patients/register-new-patient`            | POST   | Self-register as a new patient                  | Public       |\n| `/patients/view-all-doctors`                | GET    | View all doctors                                | Patient Only |\n| `/patients/doctor/availability/{doctor_id}` | GET    | View availability of a specific doctor          | Patient Only |\n| `/patients/create-new-appointment`          | POST   | Create a new appointment                        | Patient Only |\n| `/patients/doctor/appointments`             | GET    | View all appointments booked by current patient | Patient Only |\n| `/patients/doctor/appointments/{doctor_id}` | GET    | View all appointments by doctor ID              | Patient Only |\n| `/patients/medical-records/`                | GET    | View all your medical records                   | Patient Only |\n| `/patients/medical-records/{doctor_id}`     | GET    | View medical records from a specific doctor     | Patient Only |\n\n---\n\n## ⚙️ Architecture Overview\n\n- **Modular App Structure**: Organized per domain (`patients/`, `doctors/`, etc.)\n- **RBAC System**: Centralized logic in `deps/auth.py`\n- **Async Messaging**: Celery queues for non-blocking email tasks\n- **MySQL for Production**: Full relational support\n\n---\n\n## 🛡️ Security\n\n- OAuth2 Password Flow with JWT\n- Passwords hashed with bcrypt\n- Role-based endpoint access\n- Sensitive data (e.g., records) scoped by user role\n\n---\n\n## 🧱 Documentation\n\n- 📄 Swagger UI: `http://0.0.0.0:8000/docs`\n- 🗜️ Redoc: `http://0.0.0.0:8000/redoc`\n- 🗂️ Database schema: [`/docs/schema.png`](docs/schema.png)\n- 🖁️ Sequence diagram: [`/docs/sequence.png`](docs/sequence.png)\n\n---\n\n## 🧐 Design Decisions\n\n- Chose **FastAPI** for async support, clean syntax, and OpenAPI docs.\n- Modular folder structure for scalability and maintainability.\n- Celery used to handle non-blocking async tasks (e.g., email).\n- MySQL in production for advanced indexing and relational features.\n\n---\n\n## 👨‍💼 Author\n\n**Wanjang'i Gituku**  \n_Fullstack Developer_  \n📧 wanjangi.gituku@gmail.com  \n🔗 [Portfolio](https://wanjangi-gituku.github.io/online-portfolio/)\n\n---\n\n## 📃 License\n\nSee [LICENSE](https://creativecommons.org/licenses/by-nc/4.0/) details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fras-pekt%2Fappointment_scheduling_system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fras-pekt%2Fappointment_scheduling_system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fras-pekt%2Fappointment_scheduling_system/lists"}