# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

A Slack team presence tracker for monitoring the online/offline status of 26 team members at iGeolise/TravelTime. It polls the Slack API every minute via cron, stores raw presence data in per-user CSV files, and produces daily/weekly/monthly summaries and HTML reports.

## Environment Setup

Requires Python 3.11 with a virtual environment:
```bash
source myenv/bin/activate
```

Configuration is in `.env` (Slack bot token, user IDs, timezone). The central config module is `config_multi_user.py` — all other modules import from it.

## Common Commands

```bash
# Run tests
python3 test_summaries.py

# Manual presence poll (normally run by cron every minute)
python3 check_presence_team.py

# Generate summaries
python3 team_summary.py --type daily --date 2026-02-17 --csv
python3 team_summary.py --type weekly --save
python3 team_summary.py --type monthly --save
python3 team_summary.py --type all

# Rebuild all historical summaries
python3 rebuild_summaries.py

# Create master data files
python3 create_master_file.py --last-30-days
python3 create_master_file.py --start-date 2025-11-01 --end-date 2026-01-31

# Generate per-user HTML reports
python3 generate_employee_report.py --user "Tomas Šimkus" --months 3
python3 generate_employee_report.py --all --months 3

# Interactive terminal dashboard
python3 team_dashboard.py

# One-time setup / user sync
python3 setup_users.py --setup
python3 user_mapping.py --update-all
```

## Cron Schedule

Installed via `setup_cron_fresh.sh`:
- Every minute: `check_presence_team.py` (presence polling)
- Daily 00:01: `team_summary.py --type daily --csv`
- Every Monday 00:05: `team_summary.py --type weekly --save`
- 1st of month 00:10: `team_summary.py --type monthly --save`

## Architecture

### Core Modules (layered)

**`config_multi_user.py`** — Central config. Loads `.env`, defines all path constants (`BASE_DIR`, `DATA_DIR`, `RAW_DATA_DIR`, `SUMMARIES_DIR`, `LOGS_DIR`), exposes env vars, provides `setup_logging(name)` and `get_raw_data_file(date, user_id, user_name)`.

**`check_presence_team.py`** — Main orchestrator, entry point for cron. Coordinates the other three core modules to poll and store presence each minute.

**`slack_client_team.py`** — Slack API wrapper (`MultiUserSlackClient`). Calls `users.getPresence` for each user with rate limiting (1.5s delays for teams >30 users, so each cycle takes ~40s). Handles rate-limit retries.

**`user_mapping.py`** — User identity layer (`UserMapper`). Maintains `user_mappings.json` cache of Slack user metadata; falls back to Slack API on cache miss. Provides `sanitize_name()` for filesystem-safe filenames.

**`data_handler_team.py`** — Data storage and aggregation (`TeamDataHandler`). Appends presence rows to per-user daily CSVs using `fcntl.flock` for concurrency safety. Computes summaries (hours online, first/last seen) and aggregates across users and time periods.

### Singleton Pattern

All three core classes are singletons accessed via module-level factory functions: `get_slack_client()`, `get_team_handler()`, `get_user_mapper()`.

### Data Flow

1. **Every minute**: `check_presence_team.py` → Slack API → `data/raw/<user>_<date>.csv`
2. **Daily**: `team_summary.py` → reads raw CSVs → `data/summaries/team_summary.csv`
3. **On demand**: `create_master_file.py` → merges raw CSVs → master data files in `data/summaries/`
4. **On demand**: `rebuild_summaries.py` → full historical rebuild → master daily/weekly/monthly CSVs + `summary_data.json`
5. **On demand**: `generate_employee_report.py` → reads raw CSVs → HTML reports in `reports/`

### Raw Data Format

Per-user CSV (one row per minute):
```
timestamp, user_id, user_name, presence, auto_away, manual_away, last_activity, department, team
```

### Logs

Each module writes its own daily rotating log to `logs/`. Cron jobs log to `logs/cron_*.log`.