### Project Configuration (LTM)

This file contains the stable, long-term context for the project. It should be updated infrequently, primarily when core goals, tech, or patterns change.

## Core Goal

Implement an automated employee workstation activity tracking system that logs user login events and active/inactive periods on Windows machines, reports these events to a central Flask API, and provides a dashboard with daily, weekly, and monthly working time summaries.

## Tech Stack

* **Client**:

  * OS: Windows 10/11
  * Scripting: PowerShell
  * Scheduler: Windows Task Scheduler
* **Server**:

  * Language: Python 3.9+
  * Framework: Flask
  * ORM: SQLAlchemy
  * Database: SQLite (development) / PostgreSQL (production)
  * Server: Gunicorn / `flask run`
* **Frontend**:

  * HTML, CSS, JavaScript
  * Charting Library: Chart.js
* **Infrastructure**:

  * Host: On-premises LAN server
  * Networking: HTTP on corporate LAN (no external exposure)
* **DevOps & Tooling**:

  * Version Control: Git
  * Testing: pytest
  * Database Migrations: Alembic (for PostgreSQL)
  * Linting/Formatting: Flake8, Black, isort

## Critical Patterns & Conventions

* **API Design**:

  * RESTful endpoint: `POST /api/report`
  * Request payload: JSON with fields `user`, `state`, `ts` (ISO 8601)
  * Response format: JSON `{ "success": bool, "message"?: "error details" }`, HTTP 201 on success
* **Database Model**:

  * Table `work_events` with columns:

    * `id` (PK, auto-increment)
    * `user` (VARCHAR)
    * `state` (VARCHAR, e.g., "working"/"stopped")
    * `ts` (DATETIME, default now)
* **Idle Detection Logic**:

  * Fixed inactivity threshold of 5 minutes
  * State transitions: working → stopped on crossing threshold, stopped → working on activity
* **Error Handling**:

  * **PowerShell**: Wrap API calls in `try/catch`, log failures, optional retry
  * **Flask**: Global error handlers returning structured JSON errors
* **Configuration Management**:

  * Environment variables or `.env` file for API server URL, port, and DB connection string
* **Coding Standards**:

  * **Python**: PEP 8, docstrings for modules and functions
  * **PowerShell**: Verb-Noun function names, consistent two-space indentation
  * **JavaScript**: ES6+ syntax, modular code, avoid globals
* **Commit Messages**:

  * Use Conventional Commits format (e.g., `feat: add idle detection logic`)

## Key Constraints

* **Client Runtime**: Must rely solely on built-in PowerShell and Task Scheduler (no external installs)
* **Idle Threshold**: Exactly 5 minutes of inactivity
* **Authentication**: No API auth; system is LAN-restricted
* **Deployment**: Server must run on-premises within corporate LAN
* **Data Retention**: Raw event logs retained for 1 year; aggregated summaries retained indefinitely
* **Performance**: Support up to 100 client reports per minute without degradation

## Tokenization Settings

Estimation Method: Character-based
Characters Per Token (Estimate): 4