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.

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 for detailed test report.

Build Status

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