{"id":48908694,"url":"https://github.com/aojdevstudio/dental-analytics","last_synced_at":"2026-04-16T22:03:56.625Z","repository":{"id":313223659,"uuid":"1050536036","full_name":"AojdevStudio/dental-analytics","owner":"AojdevStudio","description":"Simple dental analytics dashboard that reads KPI data from Google Sheets, processes it with pandas, and displays metrics in a Streamlit web interface. Built for KamDental practice to automate daily production, collection rate, new patient count, treatment acceptance, and hygiene reappointment tracking.","archived":false,"fork":false,"pushed_at":"2026-01-30T16:33:34.000Z","size":2103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T09:42:05.410Z","etag":null,"topics":["google-sheets-api-v4","pandas","python"],"latest_commit_sha":null,"homepage":"https://unifiedental.com/","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/AojdevStudio.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":".github/CODEOWNERS","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-04T15:09:33.000Z","updated_at":"2026-01-30T16:33:35.000Z","dependencies_parsed_at":"2025-09-04T17:43:39.583Z","dependency_job_id":"04f8fcf6-4115-472f-a958-d69ba59fae9e","html_url":"https://github.com/AojdevStudio/dental-analytics","commit_stats":null,"previous_names":["aojdevstudio/dental-analytics"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AojdevStudio/dental-analytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fdental-analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fdental-analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fdental-analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fdental-analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AojdevStudio","download_url":"https://codeload.github.com/AojdevStudio/dental-analytics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AojdevStudio%2Fdental-analytics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31905896,"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":["google-sheets-api-v4","pandas","python"],"created_at":"2026-04-16T22:03:36.744Z","updated_at":"2026-04-16T22:03:56.570Z","avatar_url":"https://github.com/AojdevStudio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dental Analytics Dashboard\n\n**Multi-location dental practice KPI dashboard with real-time Google Sheets integration**\n\n📊 Version: 2.1.0 | 📄 License: MIT | 🏥 Requirements: Python 3.10+\n\n---\n\n## Description\n\nDental Analytics Dashboard is a **full-stack analytics platform** designed to **automate KPI tracking and reporting for dental practices**. It goes beyond **static spreadsheet analysis** by enabling **real-time multi-location data visualization** to support **dental practice management and performance optimization**.\n\n### Use Cases\n- **Daily KPI Monitoring**: Track production, collection rates, and patient metrics across locations\n- **Multi-Location Management**: Unified dashboard for multiple dental office locations\n- **Historical Analysis**: Time-series trending with operational date logic and weekend fallbacks\n- **Performance Reporting**: Automated calculation of 5 core dental practice KPIs\n\nDental Analytics Dashboard helps achieve **data-driven practice management** through **provider-based architecture with alias mapping and YAML configuration**.\n\n⭐ If you find this project helpful, please give it a star to support development and receive updates.\n\n---\n\n## Key Highlights\n\n### 🏗️ **Multi-Location Provider Architecture**\nSophisticated data provider system with YAML-based alias mapping that unifies access to multiple Google Sheets across dental office locations with comprehensive error handling and logging.\n\n### 📈 **Real-Time KPI Dashboard**\nStreamlit-powered web interface with customizable brand styling that displays 5 core metrics (Production, Collection Rate, New Patients, Treatment Acceptance, Hygiene Reappointment) with automatic refresh and graceful error handling.\n\nDental Analytics Dashboard is designed to address challenges such as **manual KPI calculation**, **multi-location data fragmentation**, and **time-consuming reporting workflows**—delivering **automated data collection**, **unified multi-location views**, and **real-time performance insights** through **provider-based architecture with historical data management**.\n\n📘 [Read the Full Guide](docs/guides/developer-workflow-guide.md)\n\n---\n\n## Quick Navigation\n\n- [🚀 Quick Start](#quick-start)\n- [⚙️ Configuration](#configuration)\n- [🏗️ Architecture](#architecture)\n- [📊 Dashboard Features](#dashboard-features)\n- [🔧 Development](#development)\n- [🧪 Testing](#testing)\n- [📚 Documentation](#documentation)\n- [🤝 Contributing](#contributing)\n\n---\n\n## Setup and Updates\n\n### Recommended Installation\n```bash\n# Primary installation (new setups)\nuv sync \u0026\u0026 uv run streamlit run apps/frontend/app.py\n\n# Alternative (existing setups)\npip install -r requirements.txt \u0026\u0026 streamlit run apps/frontend/app.py\n```\n\n### Installation Features\n- ✅ **Fast dependency resolution** with uv package manager\n- ✅ **Automatic Google Sheets API configuration** via service account credentials\n- ✅ **Multi-location alias mapping** through YAML configuration\n- ✅ **Brand-themed Streamlit dashboard** with custom styling\n\n### Quick Start Options\n\n#### **Dashboard Mode**\n1. **Install dependencies**: `uv sync`\n2. **Configure credentials**: Place service account JSON in `config/credentials.json`\n3. **Start dashboard**: `uv run streamlit run apps/frontend/app.py`\n4. **Access interface**: Navigate to http://localhost:8501\n5. **Select location**: Choose your location from dashboard\n\n#### **Development Mode**\n1. **Clone repository**:\n   ```bash\n   git clone https://github.com/your-org/dental-analytics.git\n   ```\n2. **Install with dev tools**:\n   ```bash\n   uv sync --dev \u0026\u0026 uv run pre-commit install\n   ```\n\n### Modular Features\nDental Analytics Dashboard can be extended to support use cases such as:\n- **Multi-practice franchise management** with centralized reporting\n- **Patient satisfaction tracking** through form response integration\n- **Financial forecasting** using historical trend analysis\n- **Staff performance metrics** with appointment and treatment data\n- **Inventory management** integration with practice management systems\n\n🧩 The provider architecture enables easy addition of new data sources and KPI calculations.\n\n---\n\n## Configuration\n\n### Prerequisites ✅ Complete\n1. ✅ Google Cloud project with Sheets API enabled\n2. ✅ Service account credentials configured\n3. ✅ Multi-sheet configuration in `config/sheets.yml`\n4. ✅ Target spreadsheet access configured with appropriate permissions\n\n### Data Source Mapping\n```yaml\n# config/sheets.yml\nsheets:\n  location_a_eod:\n    spreadsheet_id: \"YOUR_SPREADSHEET_ID_HERE\"\n    range: \"EOD - Location A Billing!A:AG\"\n    description: \"Location A end-of-day billing data\"\n  location_b_eod:\n    spreadsheet_id: \"YOUR_SPREADSHEET_ID_HERE\"\n    range: \"EOD - Location B Billing!A:AG\"\n    description: \"Location B end-of-day billing data\"\n  location_a_front:\n    spreadsheet_id: \"YOUR_SPREADSHEET_ID_HERE\"\n    range: \"Location A Front KPIs Form responses!A:Z\"\n    description: \"Location A front office KPI data\"\n  location_b_front:\n    spreadsheet_id: \"YOUR_SPREADSHEET_ID_HERE\"\n    range: \"Location B Front KPIs Form responses!A:Z\"\n    description: \"Location B front office KPI data\"\n\nlocations:\n  location_a:\n    eod: \"location_a_eod\"\n    front: \"location_a_front\"\n  location_b:\n    eod: \"location_b_eod\"\n    front: \"location_b_front\"\n\nprovider_config:\n  credentials_path: \"config/credentials.json\"\n  scopes:\n    - \"https://www.googleapis.com/auth/spreadsheets.readonly\"\n```\n\n---\n\n## Architecture\n\n### Core Technology Stack\n- **Python 3.10+**: Modern typing with union syntax\n- **Streamlit 1.30+**: Web dashboard framework\n- **pandas 2.1+**: Data processing and analysis\n- **Google Sheets API v4**: Real-time data retrieval\n- **uv**: Fast dependency management\n\n### Project Structure\n```\ndental-analytics/\n├── apps/\n│   ├── frontend/app.py              # Streamlit dashboard\n│   └── backend/\n│       ├── data_providers.py        # Multi-location provider system\n│       ├── metrics.py               # KPI calculation functions\n│       ├── historical_data.py       # Time-series data management\n│       └── chart_data.py            # Chart data processing\n├── config/\n│   ├── credentials.json             # Google API credentials\n│   └── sheets.yml                   # Multi-sheet configuration\n├── docs/stories/                    # User story documentation\n├── tests/                           # Comprehensive test suite\n└── scripts/                         # Development automation\n```\n\n### Data Flow Architecture\n```\nGoogle Sheets → DataProvider → Metrics Calculator → Streamlit UI\n     ↓              ↓              ↓               ↓\nMulti-Location   Alias Mapping   KPI Objects    Dashboard\n   Raw Data      Configuration   with History   Visualization\n```\n\n---\n\n## Dashboard Features\n\n- **5 Core KPIs**: Production Total, Collection Rate, New Patients, Treatment Acceptance, Hygiene Reappointment\n- **Multi-Location Support**: Seamless location switching between offices\n- **Brand Styling**: Customizable colors (Navy #142D54, Teal #007E9E)\n- **Real-time Data**: Live Google Sheets integration with automatic refresh\n- **Historical Analysis**: Time-series data with operational date logic\n- **Error Handling**: Graceful degradation with \"Data Unavailable\" displays\n- **Performance**: \u003c3 second load time with optimized data calls\n\n---\n\n## Development\n\n### CLI Tools\n```bash\n# Print KPIs for testing\nuv run python scripts/print_kpis.py --location location_a\nuv run python scripts/print_kpis.py --location both --json\n\n# Quality checks\n./scripts/quality-check.sh    # Comprehensive validation\n./scripts/quick-test.sh       # Fast verification\n\n# Code formatting\nuv run black apps/ tests/\nuv run ruff check apps/ tests/\n```\n\n### Code Quality\n- **Black**: Code formatting\n- **Ruff**: Modern Python linting\n- **MyPy**: Type checking\n- **Pre-commit hooks**: Automated quality gates\n\n---\n\n## Testing\n\n### Test Suite Structure\n```bash\n# Unit tests\nuv run pytest tests/test_metrics.py\nuv run pytest tests/test_data_providers.py\n\n# Integration tests\nuv run pytest tests/test_historical_data.py\nuv run pytest tests/test_location_switching.py\n\n# Manual validation\nuv run python test_calculations.py\n```\n\n### Coverage Goals\n- **90%+ coverage** for backend business logic\n- **Provider mocking** for Google Sheets API calls\n- **Comprehensive error scenarios** testing\n\n---\n\n## Resources\n\n### Documentation\n- [📖 User Stories](docs/stories/)\n- [🏗️ Architecture Overview](docs/architecture/)\n- [🚀 Development Guide](docs/guides/developer-workflow-guide.md)\n- [🧑‍💻 API Reference](docs/api/)\n\n### Support and Community\n- [💬 Discussions](https://github.com/your-org/dental-analytics/discussions)\n- [🐞 Bug Reports](https://github.com/your-org/dental-analytics/issues)\n- [🗨️ Feature Requests](https://github.com/your-org/dental-analytics/issues/new?template=feature_request.md)\n\n---\n\n## Contributing\n\nWe welcome all contributions!\n\n📋 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started.\n\n---\n\n## License\n\n**MIT** - See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Fdental-analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faojdevstudio%2Fdental-analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faojdevstudio%2Fdental-analytics/lists"}