tikker/README.md

# Tikker - Enterprise Keystroke Analytics

Keystroke analytics system providing pattern detection, statistical analysis, and behavioral profiling through distributed microservices architecture.

## System Requirements

- Docker 20.10 or later
- Docker Compose 2.0 or later
- 2GB minimum RAM
- 500MB minimum disk space

## Deployment

```bash
docker-compose up --build
```

Services become available at:
- Main API: http://localhost:8000
- AI Service: http://localhost:8001
- Visualization Service: http://localhost:8002
- ML Analytics: http://localhost:8003
- Database Viewer: http://localhost:8080 (development profile only)

## Services

| Service | Port | Function |
|---------|------|----------|
| Main API | 8000 | Keystroke statistics and analysis via C backend |
| AI Service | 8001 | Text analysis powered by OpenAI |
| Visualization | 8002 | Chart and graph generation |
| ML Analytics | 8003 | Pattern detection and behavioral analysis |
| SQLite Database | - | Data persistence |

## Core Endpoints

### Statistics API
```
GET /api/stats/daily        Daily keystroke statistics
GET /api/stats/hourly       Hourly breakdown by date
GET /api/stats/weekly       Weekly aggregation
GET /api/stats/weekday      Day-of-week comparison
```

### Word Analysis API
```
GET /api/words/top          Top N frequent words
GET /api/words/find         Statistics for specific word
```

### Operations API
```
POST /api/index             Build word index from directory
POST /api/decode            Decode keystroke token files
POST /api/report            Generate HTML activity report
```

### ML Analytics API
```
POST /patterns/detect       Identify typing patterns
POST /anomalies/detect      Detect behavior deviations
POST /profile/build         Create behavioral profile
POST /authenticity/check    Verify user identity
POST /temporal/analyze      Analyze behavior trends
POST /model/train           Train predictive models
POST /behavior/predict      Classify behavior category
```

## Command-Line Tools

Direct execution of C tools:

```bash
./build/bin/tikker-decoder input.bin output.txt
./build/bin/tikker-indexer --index --database tikker.db
./build/bin/tikker-aggregator --daily --database tikker.db
./build/bin/tikker-report --input logs_plain --output report.html
```

## Testing

```bash
pytest tests/ -v                              # All tests
pytest tests/test_services.py -v              # Integration tests
pytest tests/test_performance.py -v           # Performance tests
pytest tests/test_ml_service.py -v            # ML service tests
python scripts/benchmark.py                   # Performance benchmarks
```

## Configuration

Environment variables:

```
TOOLS_DIR=./build/bin              C tools binary directory
DB_PATH=./tikker.db                SQLite database path
LOG_LEVEL=INFO                     Logging verbosity
OPENAI_API_KEY=                    OpenAI API key for AI service
AI_SERVICE_URL=http://ai_service:8001
VIZ_SERVICE_URL=http://viz_service:8002
ML_SERVICE_URL=http://ml_service:8003
```

## Development

Build C library:
```bash
cd src/libtikker && make clean && make
```

Build CLI tools:
```bash
cd src/tools && make clean && make
```

Run services locally without Docker:
```bash
python -m uvicorn src.api.api_c_integration:app --reload
python -m uvicorn src.api.ai_service:app --port 8001 --reload
python -m uvicorn src.api.viz_service:app --port 8002 --reload
python -m uvicorn src.api.ml_service:app --port 8003 --reload
```

## Architecture

Component stack:

```
Client Applications
    │
    ├─ REST API (port 8000)
    ├─ AI Service (port 8001)
    ├─ Visualization (port 8002)
    └─ ML Analytics (port 8003)
        │
        └─ C Tools Backend (libtikker)
            │
            └─ SQLite Database
```

## Documentation

- [API Reference](docs/API.md) - Complete endpoint specifications and examples
- [ML Analytics Guide](docs/ML_ANALYTICS.md) - Pattern detection and behavioral analysis
- [Deployment Guide](docs/DEPLOYMENT.md) - Production setup and scaling
- [Performance Tuning](docs/PERFORMANCE.md) - Optimization and benchmarking
- [CLI Usage](docs/examples/CLI_USAGE.md) - Command-line tool reference

## Implementation Status

- Phase 1: Foundation (Complete)
- Phase 2: Core Converters (Complete)
- Phase 3: CLI Tools (Complete)
- Phase 4: API Integration (Complete)

Details: [MIGRATION_COMPLETE.md](MIGRATION_COMPLETE.md)

## Performance Characteristics

Typical latencies (2 CPU, 2GB RAM):

| Operation | Latency |
|-----------|---------|
| Health check | 15ms |
| Daily statistics | 80ms |
| Word frequency | 120ms |
| Pattern detection | 50-100ms |
| Anomaly detection | 80-150ms |
| Behavior profiling | 150-300ms |
| Authenticity verification | 100-200ms |

Throughput: 40-60 requests/second per service.

## Troubleshooting

**Services fail to start:**
Check logs with `docker-compose logs`. Verify port availability with `netstat -tulpn | grep 800`. Rebuild with `docker-compose build --no-cache`.

**Database locked:**
Stop services with `docker-compose down`. Remove database with `rm tikker.db`. Restart services.

**AI service timeouts:**
Verify OpenAI API key is set. Check connectivity to api.openai.com.

**Performance degradation:**
Run benchmarks with `python scripts/benchmark.py`. Check resource usage with `docker stats`. Consult [PERFORMANCE.md](docs/PERFORMANCE.md).

## Technology Stack

- C (libtikker library, 2,500+ lines)
- Python 3.11 (FastAPI framework)
- SQLite (data persistence)
- Docker (containerization)
- Pytest (testing framework)
- Matplotlib (visualization)

## Test Coverage

- 17 ML service tests: 100% pass rate
- 45+ integration tests: Comprehensive endpoint coverage
- 20+ performance tests: Latency and throughput validation

See [ML_BUILD_TEST_RESULTS.md](ML_BUILD_TEST_RESULTS.md) for detailed test report.

## Build Status

All modules compile successfully. All 17 ML analytics tests pass. Docker configuration validated. Production ready.