{"id":33319254,"url":"https://github.com/victormarlor/hyperfocus","last_synced_at":"2026-05-03T17:31:37.873Z","repository":{"id":324769266,"uuid":"1098484265","full_name":"victormarlor/HyperFocus","owner":"victormarlor","description":"Typed, test-driven FastAPI backend using SQLModel and SQLite to analyze user focus, interruptions, and time-based productivity metrics.","archived":false,"fork":false,"pushed_at":"2025-11-17T19:47:26.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-17T20:26:01.245Z","etag":null,"topics":["analytics","api-design","async-python","backend","clean-architecture","deep-work","developer-tools","docker","fastapi","focus-tracking","productivity","pydantic","pytest","python","rest-api","sqlite","sqlmodel","time-tracking"],"latest_commit_sha":null,"homepage":"","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/victormarlor.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-11-17T18:47:41.000Z","updated_at":"2025-11-17T19:47:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/victormarlor/HyperFocus","commit_stats":null,"previous_names":["victormarlor/hyperfocus"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/victormarlor/HyperFocus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victormarlor%2FHyperFocus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victormarlor%2FHyperFocus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victormarlor%2FHyperFocus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victormarlor%2FHyperFocus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/victormarlor","download_url":"https://codeload.github.com/victormarlor/HyperFocus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victormarlor%2FHyperFocus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285319005,"owners_count":27151474,"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","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"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":["analytics","api-design","async-python","backend","clean-architecture","deep-work","developer-tools","docker","fastapi","focus-tracking","productivity","pydantic","pytest","python","rest-api","sqlite","sqlmodel","time-tracking"],"created_at":"2025-11-19T20:00:29.093Z","updated_at":"2026-05-03T17:31:37.866Z","avatar_url":"https://github.com/victormarlor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Tests](https://github.com/victormarlor/HyperFocus/actions/workflows/ci.yml/badge.svg)\n\n# 🧠 HyperFocus\n### Master Your Deep Work. Track Your Interruptions.\n\n**HyperFocus** is not just another time tracker. It is a **Full-Stack Analytics Platform** designed for remote workers, developers, and students who want to understand the *science* behind their productivity. \n\nWe all feel busy, but are we **productive**? HyperFocus helps you answer that question by tracking your \"Deep Work\" sessions and analyzing exactly what breaks your flow—whether it's a phone call, a family member, or your own wandering mind.\n\n---\n\n## 🚀 Live Demo\n\nTry the application live here: **[https://hyper-focus-six.vercel.app/](https://hyper-focus-six.vercel.app/)**\n\n\u003e [!WARNING]\n\u003e **Free Tier Limitations**:\n\u003e *   **Cold Starts**: The backend is hosted on Render's free tier. If the API hasn't been used for a while, the first request may take **50+ seconds** to wake up. Please be patient! ⏳\n\u003e *   **Performance**: The database and server run on minimal resources (shared CPU/RAM). Heavy usage might cause slowness.\n\u003e *   **Data Persistence**: While data is saved, this is a demo environment. Do not use for critical production data.\n\n---\n\n## ✨ Key Features\n\n### 🛡️ Enterprise-Grade Security\n*   **Secure Authentication**: Built with **OAuth2** and **JWT** (JSON Web Tokens).\n*   **Data Protection**: Passwords hashed with **Argon2**, the winner of the Password Hashing Competition.\n*   **Role-Based Access**: Granular permissions for Users and Admins.\n\n### ⏱️ Seamless Focus Tracking\n*   **Focus Timer (Pomodoro)**: Built-in timer with presets (25m, 50m) and visual progress ring.\n*   **One-Click Sessions**: Start a \"Deep Work\" session instantly.\n*   **Frictionless Interruption Logging**: Log distractions in seconds without losing your context.\n\n### 📊 Professional Analytics Dashboard\n*   **AI Insights 🧠**: Local intelligence engine that analyzes your patterns to give personalized productivity tips.\n\n*   **Productivity Score**: A proprietary algorithm that scores your focus quality (0-100).\n*   **Interruption Breakdown**: Visual Pie Charts identifying your top distractors.\n*   **Peak Performance Hours**: Heatmaps showing *when* you are most productive.\n\n### 🎨 Premium User Experience\n*   **Modern UI**: Built with **React** and **Vite** for blazing fast performance.\n*   **Dark Mode Native**: Designed for late-night coding sessions with a custom-tuned dark palette.\n*   **Fully Responsive**: Works perfectly on your Desktop, Tablet, and Mobile.\n\n---\n\n## 🏗️ Tech Stack\n\nThis project was built using industry-standard best practices and modern technologies.\n\n### Backend (The Brain)\n*   **Language**: Python 3.11+\n*   **Framework**: [FastAPI](https://fastapi.tiangolo.com/) (High performance, easy to learn)\n*   **Database**: SQLite (Dev) / PostgreSQL (Prod ready)\n*   **ORM**: [SQLModel](https://sqlmodel.tiangolo.com/) (The power of SQLAlchemy + Pydantic)\n*   **Testing**: Pytest, Factory Boy\n\n### Frontend (The Face)\n*   **Framework**: [React](https://react.dev/) 18\n*   **Build Tool**: [Vite](https://vitejs.dev/)\n*   **State Management**: [Zustand](https://github.com/pmndrs/zustand) (Simple, scalable state)\n*   **Routing**: React Router v6\n*   **Visualization**: Recharts\n*   **Styling**: Modern CSS Variables \u0026 Responsive Design\n\n### DevOps (The Engine)\n*   **Containerization**: Docker \u0026 Docker Compose\n*   **CI/CD**: GitHub Actions (Automated Testing \u0026 Linting)\n*   **Deployment**: Ready for Railway (Backend) \u0026 Vercel (Frontend)\n\n---\n\n## 🚀 Replication Guide (How to Run This Project)\n\nWant to run HyperFocus on your own machine? Follow these steps.\n\n### Prerequisites\n*   **Docker** (Recommended) OR **Python 3.11+** \u0026 **Node.js 18+**\n*   **Git**\n\n### Option A: The \"I want it running NOW\" Method (Docker) 🐳\n\nThis will spin up the Backend, Frontend, and Database in isolated containers.\n\n1.  **Clone the Repository**\n    ```bash\n    git clone https://github.com/victormarlor/HyperFocus.git\n    cd HyperFocus\n    ```\n\n2.  **Launch with Docker Compose**\n    ```bash\n    docker-compose up --build\n    ```\n\n3.  **That's it!**\n    *   **Frontend**: Open [http://localhost](http://localhost)\n    *   **Backend API**: [http://localhost:8000](http://localhost:8000)\n    *   **API Documentation**: [http://localhost:8000/docs](http://localhost:8000/docs)\n\n---\n\n### Option B: The \"Hacker\" Method (Manual Setup) 💻\n\nIf you want to develop or modify the code, run the services locally.\n\n#### 1. Backend Setup\n\n```bash\n# Navigate to the project root\ncd HyperFocus\n\n# Create a virtual environment\npython -m venv venv\n\n# Activate it\n# Windows:\n.\\venv\\Scripts\\Activate\n# Mac/Linux:\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the server\nuvicorn app.main:app --reload\n```\n*The API is now running at `http://localhost:8000`*\n\n#### 2. Frontend Setup\n\nOpen a new terminal window.\n\n```bash\n# Navigate to the frontend directory\ncd frontend\n\n# Install Node dependencies\nnpm install\n\n# Start the development server\nnpm run dev\n```\n*The App is now running at `http://localhost:5173`*\n\n---\n\n## 🧪 Quality Assurance\n\nWe maintain high code quality standards. You can run our test suites to verify everything is working.\n\n**Backend Tests:**\n```bash\npytest\n```\n\n**Frontend Tests:**\n```bash\ncd frontend\nnpm test\n```\n\n---\n\n## 📂 Project Structure\n\nA detailed look at the architecture:\n\n```\nHyperFocus/\n├── .github/\n│   └── workflows/\n│       └── ci.yml            # CI/CD Pipeline configuration\n├── app/                      # FastAPI Backend Source\n│   ├── core/\n│   │   ├── config.py         # Environment configuration\n│   │   ├── deps.py           # Dependency Injection\n│   │   ├── logging_config.py # Logger setup\n│   │   ├── security.py       # JWT \u0026 Password hashing\n│   │   └── stats_logic.py    # Analytics business logic\n│   ├── routers/\n│   │   ├── auth.py           # Authentication endpoints\n│   │   ├── interruptions.py  # Interruption management\n│   │   ├── sessions.py       # Session management\n│   │   ├── stats.py          # Statistics endpoints\n\n│   │   └── users.py          # User management\n│   ├── db.py                 # Database connection\n│   ├── main.py               # App entry point\n│   ├── models.py             # SQLModel Database Models\n│   └── schemas.py            # Pydantic Data Schemas\n├── frontend/                 # React Frontend Source\n│   ├── src/\n│   │   ├── api/\n│   │   │   └── axios.js      # Axios instance with interceptors\n│   │   ├── components/\n│   │   │   ├── features/     # Feature Widgets (Timer, Insights)\n│   │   │   ├── layout/       # Layout \u0026 Sidebar components\n│   │   │   └── ui/           # Reusable UI (Buttons, Inputs, Cards)\n│   │   ├── pages/\n│   │   │   ├── DashboardPage.jsx\n│   │   │   ├── LoginPage.jsx\n│   │   │   ├── RegisterPage.jsx\n│   │   │   └── SessionsPage.jsx\n│   │   ├── store/\n│   │   │   └── authStore.js  # Zustand Auth Store\n│   │   ├── styles/\n│   │   │   ├── layout.css    # Responsive Layout Styles\n│   │   │   └── theme.css     # CSS Variables \u0026 Dark Mode\n│   │   ├── App.jsx           # Main App Component \u0026 Routing\n│   │   └── main.jsx          # React Entry Point\n│   ├── Dockerfile            # Frontend Dockerfile (Nginx)\n│   ├── package.json          # Frontend Dependencies\n│   └── vite.config.js        # Vite Configuration\n├── tests/                    # Backend Integration Tests\n│   ├── conftest.py           # Test Fixtures\n│   ├── test_auth.py          # Auth Tests\n│   ├── test_interruptions_api.py\n│   └── test_stats_logic.py\n├── .dockerignore             # Docker exclusion list\n├── .gitignore                # Git exclusion list\n├── docker-compose.yml        # Docker Orchestration\n├── Dockerfile                # Backend Dockerfile\n├── railway.toml              # Railway Deployment Config\n├── requirements.txt          # Backend Dependencies\n└── README.md                 # Project Documentation\n```\n\n---\n\n## 🔮 Future Roadmap\n\n*   [x] **Focus Timer**: Pomodoro integration directly in the session view.\n\n*   [x] **AI Insights**: Local heuristics engine to improve your workflow.\n*   [ ] **Mobile App**: Native React Native application.\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n*Built with ❤️ by Victormarlor*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictormarlor%2Fhyperfocus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvictormarlor%2Fhyperfocus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictormarlor%2Fhyperfocus/lists"}