Back to project Clone tikker.git Files

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 .