git clone https://molodetz.nl/retoor/tikker.git

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

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:

./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

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:

cd src/libtikker && make clean && make

Build CLI tools:

cd src/tools && make clean && make

Run services locally without Docker:

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 - Complete endpoint specifications and examples
ML Analytics Guide - Pattern detection and behavioral analysis
Deployment Guide - Production setup and scaling
Performance Tuning - Optimization and benchmarking
CLI Usage - 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

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 .