{"id":26066520,"url":"https://github.com/womb0comb0/hack-knight-25","last_synced_at":"2026-04-16T21:36:43.320Z","repository":{"id":281269029,"uuid":"944675050","full_name":"WomB0ComB0/hack-knight-25","owner":"WomB0ComB0","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-04T03:19:30.000Z","size":7719,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-04T13:34:34.895Z","etag":null,"topics":["blockchain","cryptography","ehr","full-stack","fullstack","hackathon","healthcare","nextjs","python","typescript"],"latest_commit_sha":null,"homepage":"https://hack-knight-25.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WomB0ComB0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-07T19:10:14.000Z","updated_at":"2026-02-04T03:19:39.000Z","dependencies_parsed_at":"2025-03-08T00:34:32.431Z","dependency_job_id":null,"html_url":"https://github.com/WomB0ComB0/hack-knight-25","commit_stats":null,"previous_names":["womb0comb0/hack-knight-25"],"tags_count":0,"template":false,"template_full_name":"WomB0ComB0/fullstack-web-template","purl":"pkg:github/WomB0ComB0/hack-knight-25","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WomB0ComB0%2Fhack-knight-25","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WomB0ComB0%2Fhack-knight-25/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WomB0ComB0%2Fhack-knight-25/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WomB0ComB0%2Fhack-knight-25/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WomB0ComB0","download_url":"https://codeload.github.com/WomB0ComB0/hack-knight-25/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WomB0ComB0%2Fhack-knight-25/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31905891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["blockchain","cryptography","ehr","full-stack","fullstack","hackathon","healthcare","nextjs","python","typescript"],"created_at":"2025-03-08T20:52:30.731Z","updated_at":"2026-04-16T21:36:43.284Z","avatar_url":"https://github.com/WomB0ComB0.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hack Knight '25: Secure Blockchain-Based Healthcare Management\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Next.js 14](https://img.shields.io/badge/Next.js-14-black)](https://nextjs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-latest-orange)](https://bun.sh/)\n[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.4-38B2AC)](https://tailwindcss.com/)\n\nHack Knight '25 is a decentralized healthcare management ecosystem that leverages blockchain technology to ensure the integrity, security, and portability of medical records. By combining a robust Python-based blockchain backend with a high-performance Next.js frontend, the platform provides a transparent, immutable ledger for patient data, medical appointments, and provider interactions.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Project Structure](#project-structure)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n- [Development](#development)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n---\n\n## Overview\n\nTraditional healthcare data management systems often suffer from fragmentation, lack of interoperability, and vulnerability to centralized points of failure. **Hack Knight '25** addresses these challenges by implementing a custom-built blockchain tailored for healthcare.\n\nThe system utilizes a **Proof-of-Work (PoW)** consensus mechanism to secure the ledger. Every medical record added to the system is hashed, linked to previous blocks, and distributed across the network nodes. With integrated **Fernet symmetric encryption**, sensitive patient data (PHI) remains confidential, accessible only to authorized entities holding the decryption keys.\n\n---\n\n## Features\n\n### Core Blockchain Engine\n- **Custom Blockchain Core**: Native implementation of a linked-block structure with SHA-256 cryptographic hashing.\n- **Proof-of-Work (PoW)**: Robust mining algorithm (Nonce-based) ensures network security and prevents record tampering.\n- **Immutable Ledger**: Once a medical record is mined into a block, it cannot be altered without recalculating every subsequent hash.\n- **Consensus Logic**: Automatic conflict resolution utilizing the \"Longest Chain Rule\" for multi-node synchronization.\n\n### Healthcare \u0026 Security\n- **Medical Encryption Layer**: Integrated symmetric encryption (via `medical_encryption.key`) to protect Protected Health Information (PHI) at rest.\n- **Healthcare Data Models**: Specialized schemas for appointments, patient registration, and provider credentials.\n- **Auditability**: Complete, timestamped history of every medical transaction.\n\n### Modern Web Experience\n- **Next.js 14 Dashboard**: A high-performance, React-based interface for patients and providers.\n- **Real-time Blockchain Metrics**: Visual representation of chain height, mining difficulty, and transaction volume via the `BlockchainInfoCard`.\n- **Responsive UI/UX**: Built with Radix UI, Tailwind CSS, and Shadcn/UI for a seamless mobile and desktop experience.\n- **Interactive Chat**: Integrated patient-provider communication interface.\n- **Storybook Integration**: Documented and isolated UI component development for design consistency.\n\n---\n\n## Architecture\n\nThe project follows a decoupled micro-service architecture, separating the cryptographic heavy-lifting of the blockchain from the user-facing application.\n\n```mermaid\ngraph TD\n    subgraph Frontend_Layer [Next.js 14 Client]\n        Dashboard[Patient Dashboard]\n        Register[Registration System]\n        Appts[Appointment Manager]\n        Chat[Provider Chat UI]\n        API_Client[API Client \u0026 Hooks]\n    end\n\n    subgraph API_Gateway [Communication Layer]\n        Flask_API[Flask REST Server]\n        Middleware[Auth \u0026 Logging]\n    end\n\n    subgraph Blockchain_Engine [Core Backend]\n        BC_Manager[Blockchain Manager]\n        Mempool[Transaction Pool]\n        Miner[PoW Mining Engine]\n        Enc[Symmetric Encryption Layer]\n        Consensus[Node Consensus Logic]\n    end\n\n    subgraph Persistence [Data Layer]\n        Ledger[(Immutable Ledger)]\n        State[(Node State)]\n        Keys[(Medical Keys)]\n    end\n\n    Dashboard --\u003e API_Client\n    API_Client --\u003e Flask_API\n    Flask_API --\u003e BC_Manager\n    BC_Manager --\u003e Mempool\n    Mempool --\u003e Miner\n    Miner --\u003e Ledger\n    BC_Manager --\u003e Enc\n    Enc --\u003e Keys\n    Flask_API --\u003e Consensus\n    Consensus --\u003e State\n```\n\n---\n\n## Project Structure\n\n### Blockchain Backend (`/blockchain`)\n- `blockchain.py`: The core logic for block creation, hashing, and Proof-of-Work.\n- `app.py`: Flask-based REST API exposing blockchain functionality.\n- `healthcare_structure.py`: Definitions for medical records and healthcare-specific data objects.\n- `auth_service.py`: Handles user authentication and role-based access.\n- `medical_encryption.key`: The symmetric key used for PHI encryption.\n\n### Frontend (`/frontend`)\n- `src/app/`: Next.js App Router directories for `dashboard`, `chat`, `signin`, and `register`.\n- `src/components/`: Modular UI components, including specialized `blockchain-info-card` and `patient-dashboard`.\n- `src/hooks/`: Custom React hooks for data fetching and UI state.\n- `src/lib/utils.ts`: Utility functions for Tailwind class merging and data formatting.\n\n---\n\n## Quick Start\n\n### Prerequisites\n- **Python**: 3.9+\n- **Node.js**: 18+ or **Bun** (Recommended)\n- **Git**\n\n### 1. Installation\n\nClone the repository and install dependencies for both the frontend and the blockchain service.\n\n```bash\n# Clone the repository\ngit clone https://github.com/WomB0ComB0/hack-knight-25.git\ncd hack-knight-25\n\n# Install Frontend dependencies\ncd frontend\nbun install\n\n# Install Backend dependencies\ncd ../blockchain\npip install -r requirements.txt\n```\n\n### 2. Launching the Services\n\nYou can start the services independently.\n\n**Start the Blockchain Backend:**\n```bash\ncd blockchain\npython app.py\n```\n*The backend will run on: `http://localhost:5000`*\n\n**Start the Next.js Frontend:**\n```bash\ncd frontend\nbun run dev\n```\n*The frontend will run on: `http://localhost:3000`*\n\n---\n\n## Usage\n\n### Mining a Block\nNew medical transactions are held in a \"mempool\" (pending transactions) until they are mined. To finalize transactions and secure them into the ledger:\n```bash\ncurl -X GET http://localhost:5000/mine\n```\n\n### Adding a Medical Record\nSubmit a POST request with the transaction details. The `medical_data` field is automatically encrypted by the `MedicalEncryption` service before storage.\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n-d '{\n  \"sender\": \"Doctor_ID_082\",\n  \"recipient\": \"Patient_UUID_44\",\n  \"amount\": 1,\n  \"medical_data\": \"Diagnosis: Type II Diabetes. Recommendation: Low glycemic diet.\"\n}' \\\nhttp://localhost:5000/transactions/new\n```\n\n### Registering Network Nodes\nTo form a decentralized cluster, register neighboring nodes to enable consensus:\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n-d '{\n  \"nodes\": [\"http://192.168.1.15:5000\", \"http://192.168.1.20:5000\"]\n}' \\\nhttp://localhost:5000/nodes/register\n```\n\n---\n\n## Configuration\n\n### Backend Configuration (`blockchain/config.ini`)\n| Parameter | Description | Default |\n| :--- | :--- | :--- |\n| `difficulty` | Number of leading zeros required for a valid hash (PoW) | `4` |\n| `mining_reward` | Tokens granted to the node that successfully mines a block | `1` |\n| `node_identifier` | Unique UUID for the current network node | `random-uuid` |\n\n### Frontend Environment (`frontend/.env`)\n```env\nNEXT_PUBLIC_BLOCKCHAIN_API=http://localhost:5000\nNEXT_PUBLIC_APP_URL=http://localhost:3000\n```\n\n---\n\n## API Reference\n\n### Blockchain Core API\n| Endpoint | Method | Description |\n| :--- | :--- | :--- |\n| `/chain` | GET | Returns the full blockchain ledger and current chain length. |\n| `/mine` | GET | Triggers the mining process for all pending transactions. |\n| `/transactions/new` | POST | Creates a new medical transaction/record. |\n| `/nodes/register` | POST | Adds new neighbor nodes to the internal registry. |\n| `/nodes/resolve` | GET | Runs the consensus algorithm to ensure the node has the longest chain. |\n\n### Application \u0026 Scheduling API\n| Endpoint | Method | Description |\n| :--- | :--- | :--- |\n| `/api/appointments` | GET | Fetches all scheduled medical appointments. |\n| `/api/appointments` | POST | Creates a new appointment entry in the system. |\n| `/api/appointments/[id]` | DELETE | Removes a specific appointment by ID. |\n| `/api/health` | GET | Checks the health status of the API and database connectivity. |\n\n---\n\n## Development\n\n### UI Component Development\nThe project uses **Storybook** for developing UI components in isolation. This ensures that the design system remains robust across the dashboard.\n```bash\ncd frontend\nbun run storybook\n```\n\n### Code Style \u0026 Linting\n- **Frontend**: Prettier and ESLint are configured for TypeScript.\n- **Backend**: Follows PEP 8 standards.\n\n### Core Logic: Proof of Work\nThe mining algorithm resides in `blockchain/blockchain.py`:\n```python\ndef proof_of_work(self, last_proof):\n    proof = 0\n    while self.valid_proof(last_proof, proof) is False:\n        proof += 1\n    return proof\n```\n\n---\n\n## Contributing\n\n1. **Fork the Repository**: Create your own fork of the project.\n2. **Create a Branch**: `git checkout -b feature/amazing-feature`\n3. **Commit Changes**: `git commit -m 'Add some amazing feature'`\n4. **Push to Branch**: `git push origin feature/amazing-feature`\n5. **Open a Pull Request**: Submit your changes for review.\n\n---\n\n## Roadmap\n\n- [ ] **Smart Contracts**: Implement programmable medical logic (e.g., auto-release of insurance funds).\n- [ ] **Zero-Knowledge Proofs (ZKP)**: Allow patients to prove eligibility/health status without revealing underlying PHI.\n- [ ] **Mobile Integration**: Dedicated React Native app for patient access on the go.\n- [ ] **Multi-Signature Records**: Require both doctor and patient signatures before a record is committed to the block.\n- [ ] **IPFS Integration**: Move large medical images (DICOM/X-Rays) to IPFS, storing only the hash on the blockchain.\n\n---\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwomb0comb0%2Fhack-knight-25","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwomb0comb0%2Fhack-knight-25","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwomb0comb0%2Fhack-knight-25/lists"}