{"id":34733015,"url":"https://github.com/onfranciis/booking-headless","last_synced_at":"2026-05-01T20:31:25.057Z","repository":{"id":322057756,"uuid":"1087920312","full_name":"onfranciis/booking-headless","owner":"onfranciis","description":"An open-source backend for service providers, enabling businesses and professionals to connect with their customers, manage appointments, and integrate bookings with Google Calendar.","archived":false,"fork":false,"pushed_at":"2025-12-18T19:13:21.000Z","size":298,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-26T13:57:01.147Z","etag":null,"topics":["actix","actix-web","calendly","google","open-source","oss","postgresql","redis","rust","swagger"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/onfranciis.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T23:07:36.000Z","updated_at":"2025-12-18T19:13:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/onfranciis/booking-headless","commit_stats":null,"previous_names":["onfranciis/booking-headless"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/onfranciis/booking-headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onfranciis%2Fbooking-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onfranciis%2Fbooking-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onfranciis%2Fbooking-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onfranciis%2Fbooking-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onfranciis","download_url":"https://codeload.github.com/onfranciis/booking-headless/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onfranciis%2Fbooking-headless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32512662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["actix","actix-web","calendly","google","open-source","oss","postgresql","redis","rust","swagger"],"created_at":"2025-12-25T03:17:41.841Z","updated_at":"2026-05-01T20:31:25.031Z","avatar_url":"https://github.com/onfranciis.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📅 Booking Headless API\n\n![Rust CI](https://github.com/onfranciis/booking-headless/actions/workflows/rust.yml/badge.svg)\n![Rust Version](https://img.shields.io/badge/rust-1.80%2B-orange?logo=rust)\n![Docker](https://img.shields.io/badge/docker-ready-blue?logo=docker)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n\u003e **A high-performance, headless appointment scheduling engine.**\n\nThis is a client-agnostic backend service designed to power scheduling for **Web, Mobile (iOS/Android), and Desktop** applications. By strictly decoupling business logic from the presentation layer, this API serves as a central, authoritative decision engine for time management across all your client platforms.\n\nBuilt with **Rust** and **Actix-Web**, it features two-way Google Calendar synchronization, atomic database transactions, and a \"Fail-Fast\" configuration philosophy.\n\n## 🏗 Architecture \u0026 Flow\n\nThis project follows a **Headless API** architecture. It exposes pure JSON endpoints via REST, allowing any consumer to integrate complex scheduling logic without reimplementing the math.\n\n### 1. The Availability Engine\n\nThe core complexity lies in determining when a user is \"free.\" The system aggregates data from multiple sources to serve a single source of truth to the client.\n\n1.  **Business Rules:** Recurring opening hours defined in PostgreSQL.\n2.  **External Conflicts:** Real-time \"Free/Busy\" checks against Google Calendar.\n3.  **Internal Conflicts:** Existing appointments in the database.\n\nThe engine normalizes all times to UTC, calculates overlaps, and generates available slots.\n\n```mermaid\nsequenceDiagram\n    participant Client as Mobile / Web App\n    participant API as Rust API\n    participant Cache as Redis\n    participant DB as PostgreSQL\n    participant Google as Google Calendar API\n\n    Client-\u003e\u003eAPI: GET /users/{id}/slots?date=2025-01-01\n    API-\u003e\u003eCache: Check for cached slots\n    alt Cache Hit\n        Cache--\u003e\u003eAPI: Return JSON\n        API--\u003e\u003eClient: Return Slots\n    else Cache Miss\n        API-\u003e\u003eDB: Fetch Business Hours (Rules)\n        API-\u003e\u003eDB: Fetch Existing Appts (Internal Blocks)\n        API-\u003e\u003eGoogle: Fetch Free/Busy (External Blocks)\n        Note right of API: Normalize to UTC \u0026\u003cbr/\u003eCalculate Overlaps\n        API-\u003e\u003eCache: Store Result (TTL 5 min)\n        API--\u003e\u003eClient: Return Calculated Slots\n    end\n```\n\n### 2\\. The Booking Transaction\n\nTo ensure data integrity, bookings are handled atomically. If the sync with Google Calendar fails, the database transaction rolls back, ensuring the system never enters an inconsistent state.\n\n```mermaid\nflowchart TD\n    A[Client Request] --\u003e B{Validate Inputs}\n    B -- Invalid --\u003e C[400 Bad Request]\n    B -- Valid --\u003e D[Start DB Transaction]\n    D --\u003e E[Lock Row / Check Availability]\n    E --\u003e F[Insert Appointment]\n    F --\u003e G[Sync to Google Calendar]\n    G -- Success --\u003e H[Commit Transaction]\n    G -- Failure --\u003e I[Rollback Transaction]\n    H --\u003e J[Invalidate Redis Cache]\n    J --\u003e K[201 Created]\n    I --\u003e L[500 Internal Error]\n```\n\n## ⚡ Key Features\n\n### 🛡 Reliability \u0026 Safety\n\n- **Fail-Fast Configuration:** The application validates all environment variables and connections at startup. It refuses to boot in a broken state.\n- **Atomic Transactions:** Uses `sqlx` transactions to ensure bookings are all-or-nothing.\n- **Type-Safe APIs:** Leveraging Rust's strong type system to prevent runtime errors.\n\n### 🌍 Timezone Intelligence\n\n- **Client Agnostic:** Stores everything in UTC. Clients receive ISO 8601 strings and render in the user's local time.\n- **Complex Math:** Handles \"Midnight Crossing\" logic (e.g., shifts starting at 11 PM and ending 4 AM) using `chrono-tz` and `time`.\n\n### 🚀 Performance\n\n- **Connection Pooling:** Tuned `PgPool` for efficient database access.\n- **Redis Caching:** Availability slots are cached to reduce latency and API quotas.\n- **Zero-Cost Abstractions:** Uses pure Rust logic for slot generation, minimizing heap allocations.\n\n### 🔌 Integrations\n\n- **Google OAuth2:** Secure authentication flow.\n- **Google Calendar:** Two-way sync (Free/Busy checks + Event creation).\n- **Google Cloud Storage:** Signed URLs for secure, direct-to-bucket profile image uploads.\n\n## 🛠 Tech Stack\n\n| Component     | Technology | Description                                    |\n| :------------ | :--------- | :--------------------------------------------- |\n| **Language**  | Rust       | 2021 Edition                                   |\n| **Framework** | Actix Web  | High-performance async web framework           |\n| **Database**  | PostgreSQL | Reliability and relational data integrity      |\n| **ORM/Query** | SQLx       | Async, compile-time checked SQL queries        |\n| **Cache**     | Redis      | `deadpool-redis` for connection pooling        |\n| **Docs**      | Utoipa     | Auto-generated OpenAPI (Swagger) documentation |\n| **Runtime**   | Tokio      | Asynchronous runtime                           |\n\n## 📚 API Documentation\n\nWhen running locally, the interactive Swagger UI is available at:\n`http://localhost:8080/swagger-ui/`\n\nThis provides a complete definition of all endpoints, request schemas, and response types.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Rust (Latest Stable)\n- Docker \u0026 Docker Compose\n- Google Cloud Console Project (Credentials required)\n\n### Installation\n\n1.  **Clone the Repository**\n\n     ```bash\n    git clone https://github.com/onfranciis/booking-headless.git\n    cd booking-headless\n    ```\n\n2.  **Environment Setup**\n    Copy the example environment file and fill in your credentials.\n\n    ```bash\n    cp .env.example .env\n    ```\n\n3.  **Start Infrastructure**\n    Spin up Postgres and Redis in the background.\n\n    ```bash\n    docker-compose up -d db redis\n    ```\n\n4.  **Run Migrations**\n    Initialize the database schema.\n\n    ```bash\n    sqlx migrate run\n    ```\n\n5.  **Run the Server**\n\n    ```bash\n    cargo run\n    ```\n\n## 🧪 Testing\n\nThe project includes unit tests for pure logic (math) and integrations.\n\n```bash\n# Run logic tests (No DB required)\ncargo test\n```\n\n## 🤝 Contributing\n\nWe welcome contributions from the community\\! Whether it's updating docs or optimizing a query, your help is welcome.\n\n👉 **[Read our Contributing Guide](./CONTRIBUTING.md)** for details on the architecture, testing strategy, and code of conduct.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENCE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonfranciis%2Fbooking-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonfranciis%2Fbooking-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonfranciis%2Fbooking-headless/lists"}