{"id":29098812,"url":"https://github.com/creepymemes/barbermanager","last_synced_at":"2025-12-30T22:22:35.606Z","repository":{"id":298581195,"uuid":"974837591","full_name":"CreepyMemes/barbermanager","owner":"CreepyMemes","description":"BarberManager - Management software for barber shops","archived":false,"fork":false,"pushed_at":"2025-06-26T16:03:50.000Z","size":18599,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-26T16:44:19.615Z","etag":null,"topics":["api","backend","barbershop","django","django-rest-framework","docker","frontend","fullstack","manager-system","python","react","vite"],"latest_commit_sha":null,"homepage":"https://barbermanager.creepymemes.com/","language":"Python","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/CreepyMemes.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}},"created_at":"2025-04-29T11:36:05.000Z","updated_at":"2025-06-26T16:03:55.000Z","dependencies_parsed_at":"2025-06-11T21:47:17.504Z","dependency_job_id":"b1f04fdd-ea24-457f-8a85-bd1050122cb9","html_url":"https://github.com/CreepyMemes/barbermanager","commit_stats":null,"previous_names":["creepymemes/barbermanager"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CreepyMemes/barbermanager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CreepyMemes%2Fbarbermanager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CreepyMemes%2Fbarbermanager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CreepyMemes%2Fbarbermanager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CreepyMemes%2Fbarbermanager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CreepyMemes","download_url":"https://codeload.github.com/CreepyMemes/barbermanager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CreepyMemes%2Fbarbermanager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262449721,"owners_count":23312998,"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":["api","backend","barbershop","django","django-rest-framework","docker","frontend","fullstack","manager-system","python","react","vite"],"created_at":"2025-06-28T15:08:01.930Z","updated_at":"2025-12-30T22:22:35.598Z","avatar_url":"https://github.com/CreepyMemes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n  \u003cimg src=\"./frontend/assets/images/logo.webp\" height=\"100px\" alt=\"BarberManager Logo\"/\u003e\r\n  \u003ch1\u003eBarberManager\u003c/h1\u003e\r\n\r\n[![Deploy to Production](https://github.com/CreepyMemes/barbermanager/actions/workflows/deploy.yml/badge.svg?branch=master)](https://github.com/CreepyMemes/barbermanager/actions/workflows/deploy.yml)\r\n[![BarberManager](https://img.shields.io/badge/BarberManager-Live%20Website-F38020?labelColor=555555\u0026logo=cloudflare\u0026logoColor=white)](https://barbermanager.creepymemes.com/)\r\n[![API Documentation](https://img.shields.io/badge/Swagger%20UI-API%20Documentation-6ec225?labelColor=555555\u0026logo=swagger\u0026logoColor=white)](https://barbermanager.creepymemes.com/api/)\r\n\r\n\u003c/div\u003e\r\n\r\n## Overview\r\n\r\nBarberManager is a containerized barber shop management system web application.\r\n\r\nIt provides an appointment booking system for clients, availability management for barbers, and automated reminders.\r\n\r\nThe tech stack uses **React** (Vite) frontend, **Django** backend, and relies on **Docker Compose** for easy cross-platform development \u0026 deployment.\r\n\r\n## Table of Contents\r\n\r\n- [Overview](#overview)\r\n- [Table of Contents](#table-of-contents)\r\n- [Features](#features)\r\n- [Architecture](#architecture)\r\n- [API Documentation](#api-documentation)\r\n- [Live Deployment](#live-deployment)\r\n- [Quickstart](#quickstart)\r\n  - [Requirements](#requirements)\r\n  - [Development Workflow](#development-workflow)\r\n    - [Clone the repository](#clone-the-repository)\r\n    - [Build and launch all containers](#build-and-launch-all-containers)\r\n    - [(Optional) Reset dev environment](#optional-reset-dev-environment)\r\n- [Development Guide](#development-guide)\r\n  - [Backend (Django)](#backend-django)\r\n    - [Configuration](#configuration)\r\n    - [Dependencies](#dependencies)\r\n    - [Migrations](#migrations)\r\n    - [SuperUser](#superuser)\r\n    - [Run tests](#run-tests)\r\n    - [Model diagram](#model-diagram)\r\n  - [Frontend (React + Vite)](#frontend-react--vite)\r\n    - [Dependencies](#dependencies-1)\r\n    - [Run tests](#run-tests-1)\r\n- [Production Workflow](#production-workflow)\r\n  - [Deployment](#deployment)\r\n    - [CI/CD Workflow Overview](#cicd-workflow-overview)\r\n\r\n## Features\r\n\r\n- 💇‍♂️ **Barber Availability**: Admins define 1-hour slot schedules for each barber.\r\n- 📅 **Client Appointments**: Clients can book available slots with their chosen barber \u0026 service(s).\r\n- ⏰ **Reminders \u0026 Automation**: Email reminders and automatic appointment status updates via Celery tasks.\r\n- 💬 **Client Reviews**: Only permitted after completed appointments; one per client-barber pair.\r\n- 📊 **Dashboard Statistics**: See business insights \u0026 feedback.\r\n- 🐳 **Portable Development**: Containerized via Docker and VSCode Dev Containers for zero-conf dev setup.\r\n- ♾️ **DevOps \u0026 CI/CD**: GitHub Actions automate testing, linting, and deployment.\r\n\r\n## Architecture\r\n\r\n```mermaid\r\nflowchart TD\r\n    US([User \u003cbr\u003e Browser/Mobile])\r\n\r\n    RP[Reverse Proxy: Nginx]\r\n\r\n    subgraph FrontendInfra[Frontend Infrastructure]\r\n      subgraph frontend[Container: 'frontend']\r\n        SF[Server: Nginx]\r\n        BL[Builder: Vite]\r\n        FE[Frontend: React SPA]\r\n      end\r\n    end\r\n\r\n    subgraph BackendInfra[Backend Infrastructure]\r\n      subgraph backend[Container: 'backend']\r\n        SB[WSGI: Gunicorn]\r\n        BE[Backend: Django REST API]\r\n      end\r\n\r\n      subgraph celery[Container: 'celery']\r\n          CW[[Worker: Celery]]\r\n      end\r\n\r\n      subgraph celery-beat[Container: 'celery-beat']\r\n          CB[[Beat: Celery]]\r\n      end\r\n\r\n      subgraph db[Container: 'db']\r\n        PG[(Datatbase: Postgres)]\r\n      end\r\n\r\n      subgraph redis[Container: 'redis']\r\n        RD[(Broker: Redis)]\r\n      end\r\n    end\r\n\r\n    %% User\r\n    US -- HTTPS --\u003e RP\r\n    RP -- Routes --\u003e SF\r\n    RP -- Routes --\u003e SB\r\n\r\n    %% Frontend Infrastructutre\r\n    SF -- Serves --\u003e BL\r\n    BL -- Builds --\u003e FE\r\n\r\n    %% Backend Infrastructutre\r\n    SB -- Serves --\u003e BE\r\n    BE -- ORM Access --\u003e PG\r\n    CW -- ORM Access (for task logic) --\u003e PG\r\n    CW -- Pulls tasks --\u003e RD\r\n    CB -- Enqueues tasks --\u003e RD\r\n    BE .-\u003e CW\r\n    BE .-\u003e CB\r\n\r\n    style FrontendInfra fill:#0005\r\n    style BackendInfra fill:#0005\r\n\r\n    style frontend fill:#2496ED50\r\n    style backend fill:#2496ED50\r\n    style celery fill:#2496ED50\r\n    style celery-beat fill:#2496ED50\r\n    style db fill:#2496ED50\r\n    style redis fill:#2496ED50\r\n\r\n    style SF fill:#009639\r\n    style BL fill:#646CFF\r\n    style FE fill:#61DAFB\r\n    style FE color:#000\r\n    style RP fill:#009639\r\n    style BE fill:#092e20\r\n    style SB fill:#499848\r\n    style RD fill:#FF4438\r\n    style PG fill:#4169E1\r\n    style CW fill:#37814A\r\n    style CB fill:#37814A\r\n```\r\n\r\n## API Documentation\r\n\r\nBarberManager offers extensive, interactive API documentation using **Swagger UI**.  \r\nYou can explore all backend endpoints, models, request/response formats, and try out live requests directly in your browser.\r\n\r\n➡️ **[View the API Documentation here.](https://barbermanager.creepymemes.com/api/)**  \r\nOr click the green \"Swagger UI\" badge at the top of this README.\r\n\r\nTypical API documentation features:\r\n\r\n- **Visual interface** for exploring all available endpoints and methods.\r\n- **Live \"Try it Out\"** feature for authenticating and testing API calls.\r\n- **Model schemas** and required/optional field details for each operation.\r\n\r\nThis documentation is always up-to-date with the deployed backend and is a helpful resource for frontend developers, integrators, and testers.\r\n\r\n## Live Deployment\r\n\r\nYou can try out BarberManager yourself on our live, production website!\r\n\r\n➡️ **[Open the Live Website](https://barbermanager.creepymemes.com/)**  \r\nOr click the orange \"BarberManager\" badge at the top of this README.\r\n\r\nThe live deployment features:\r\n\r\n- The latest available version, always kept up to date through automated CI/CD.\r\n- Full access to the web app's core features as described in this documentation.\r\n- A real working environment for testing, demos, or exploring as a developer, admin, or client.\r\n\r\n## Quickstart\r\n\r\n### Requirements\r\n\r\n- [Docker](https://docs.docker.com/engine/install/)\r\n- [Docker Compose](https://docs.docker.com/compose/install/)\r\n- [VSCode](https://code.visualstudio.com/) (+ [Dev Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers))\r\n\r\n### Development Workflow\r\n\r\nThis section is about the development workflow in programming and testing the application on local machine.\r\n\r\n\u003e [!TIP]\r\n\u003e If you want to run **VSCode** inside the backend container.\r\n\u003e When you open the project `backend` or `frontend` foldlers in **VSCode**,\r\n\u003e it shoullt automaticaly detect the `.devcontainer` configurations.\r\n\u003e\r\n\u003e If it doesn't detect it or you ignore the notification you can:\r\n\u003e Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on macOS).\r\n\u003e Select `Remote-Containers: Reopen in Container`.\r\n\r\n#### Clone the repository\r\n\r\nIf the repository is public:\r\n\r\n```bash\r\ngit clone https://github.com/CreepyMemes/barbermanager.git\r\ncd barbermanager/\r\n```\r\n\r\nIf the repository is private:\r\n\r\n\u003e [!IMPORTANT]\r\n\u003e Change **TOKEN** to your github token\r\n\r\n```bash\r\ngit clone https://CreepyMemes:TOKEN@github.com/CreepyMemes/barbermanager.git\r\ncd barbermanager\r\n```\r\n\r\n#### Build and launch all containers\r\n\r\n```bash\r\ndocker compose -f docker-compose.dev.yml --env-file .env.dev up --build\r\n```\r\n\r\n- Frontend: [http://localhost:3000](http://localhost:3000)\r\n- Backend: [http://localhost:8000](http://localhost:8000)\r\n\r\n#### (Optional) Reset dev environment\r\n\r\n```bash\r\ndocker compose -f docker-compose.dev.yml down --volumes --remove-orphans\r\n```\r\n\r\n## Development Guide\r\n\r\n### Backend (Django)\r\n\r\nThe Django dev server reloads automatically on code changes.\r\n\r\n\u003e [!IMPORTANT]\r\n\u003e Run the following commands _inside_ the container.\r\n\u003e by running the following command:\r\n\u003e\r\n\u003e ```bash\r\n\u003e docker compose -f docker-compose.dev.yml --env-file .env.dev exec -it backend sh\r\n\u003e ```\r\n\r\n#### Configuration\r\n\r\nCreate a new `.env` file in root directory, and enter your credentials there, follow the example at `.env.example`:\r\n\r\n```sh\r\n# Django config\r\nSECRET_KEY=your-super-secret-key-here\r\nDJANGO_ALLOWED_HOSTS=*\r\nDJANGO_SETTINGS_MODULE=config.settings.dev # change .dev or .prod\r\n\r\n# Database config\r\nPOSTGRES_HOST=db\r\nPOSTGRES_PORT=5432\r\nPOSTGRES_DB=mydb\r\nPOSTGRES_USER=myuser\r\nPOSTGRES_PASSWORD=mypassword\r\n\r\n# Email config\r\nEMAIL_HOST='smtp.server.com'\r\nEMAIL_PORT=587\r\nEMAIL_HOST_USER='your.stmp@email.com'\r\nEMAIL_HOST_PASSWORD='your stmp pass here'\r\n```\r\n\r\n#### Dependencies\r\n\r\nTo install new dependencies, for either base, prod or dev:\r\n\r\n```bash\r\npip install \u003cpackage\u003e\r\npip freeze \u003e requirements/base.txt\r\npip freeze \u003e requirements/dev.txt\r\npip freeze \u003e requirements/prod.txt\r\n```\r\n\r\n#### Migrations\r\n\r\nTo migrate database:\r\n\r\n```bash\r\npython manage.py migrate\r\n```\r\n\r\n#### SuperUser\r\n\r\nTo create an admin user:\r\n\r\n```bash\r\npython manage.py createsuperuser\r\n```\r\n\r\n#### Run tests\r\n\r\nTo simply run all tests:\r\n\r\n```bash\r\npython manage.py test api\r\n```\r\n\r\nTo check test coverage, we use `coverage` package that highlights which part of the codebase are being tested:\r\n\r\n```bash\r\ncoverage run --source=\".\" manage.py test api\r\ncoverage html\r\n```\r\n\r\n#### Model diagram\r\n\r\nTo generate a models diagram, we use `django-extensions` package that includes a diagram generator for all the implemented models found in the project, to use:\r\n\r\n```bash\r\npython manage.py graph_models -a -o models_diagram.png\r\n```\r\n\r\n### Frontend (React + Vite)\r\n\r\nVite provides automatic hot-reloading when frontend files are modified.\r\n\r\n\u003e [!IMPORTANT]\r\n\u003e Run the following commands _inside_ the container.\r\n\u003e by running the following command:\r\n\u003e\r\n\u003e ```bash\r\n\u003e docker compose -f docker-compose.dev.yml --env-file .env.dev exec -it frontend sh\r\n\u003e ```\r\n\r\n#### Dependencies\r\n\r\nTo install new dependencies, for either prod or dev:\r\n\r\n```bash\r\nnpm install \u003cpackage\u003e --save-dev\r\nnpm install \u003cpackage\u003e\r\n```\r\n\r\n#### Run tests\r\n\r\n[TODO]\r\n\r\n## Production Workflow\r\n\r\n### Deployment\r\n\r\nThe deployment process is **fully automated** via [GitHub Actions](https://github.com/features/actions). The CI/CD pipeline is triggered by every **Pull Request**:\r\n\r\n#### CI/CD Workflow Overview\r\n\r\n```mermaid\r\nflowchart TD\r\n    PR(🔀 Pull Request)\r\n    Tests{{🧪 Runs Tests}}\r\n    Passed([✅ Able to Merge])\r\n    Failed([❌ Cannot Merge])\r\n    Deployment(🚀 Runs Deployment)\r\n    PR --\u003e Tests\r\n    Tests -- Passed --\u003e Passed\r\n    Tests -- Failed --\u003e Failed\r\n    Passed -- Merge --\u003e Deployment\r\n```\r\n\r\n1. **Build \u0026 Test:**  \r\n   All pull requests trigger automated builds and tests in a production-like Docker environment.\r\n2. **Merge \u0026 Deploy Automatically:**  \r\n   If tests pass, the pull request can be merged.  \r\n   Once merged, the code is automatically deployed to the server via SSH.\r\n\r\n- Environment variables are provided securely with GitHub Secrets.\r\n- Deployments use a custom `deploy.sh` script for zero downtime.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreepymemes%2Fbarbermanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcreepymemes%2Fbarbermanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreepymemes%2Fbarbermanager/lists"}