work-tracing/project_config.md

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 10 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 10 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