Foundation Setup

.env.example

@@ -0,0 +1,13 @@
+# GCP Configuration
+GCP_PROJECT_ID="your-project-id"
+FIRESTORE_DATABASE="default"
+
+# Buffer Configuration
+BUFFER_SIZE=100
+BUFFER_TIMEOUT=5.0
+
+# Sequencer Configuration
+NUM_PARTITIONS=16
+
+# Logging
+LOG_LEVEL="INFO"

.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --frozen --all-extras
+
+    - name: Lint
+      run: |
+        uv run ruff check src/ tests/
+
+    - name: Check formatting
+      run: |
+        uv run ruff format --check src/ tests/
+
+    - name: Type check
+      run: |
+        uv run mypy src/eventkit
+
+    - name: Run tests
+      run: |
+        uv run pytest --cov=src/eventkit --cov-report=term-missing --cov-report=xml
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false

.gitignore

@@ -41,6 +41,9 @@ htmlcov/
 .tox/
 .mypy_cache/
 .ruff_cache/
+*.cover
+.hypothesis/
+.cache
 
 # Environment variables
 .env
@@ -52,3 +55,16 @@ docs/_build/
 
 # Distribution / packaging
 pip-wheel-metadata/
+
+# Logs
+*.log
+logs/
+
+# GCP credentials (just in case)
+*.json
+!pyproject.json
+!package.json
+
+# OS
+.DS_Store
+Thumbs.db

.pre-commit-config.yaml

@@ -1,10 +1,20 @@
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+  # Use system (uv-managed) ruff for consistency with CI
+  - repo: local
     hooks:
-      - id: ruff
-        args: [--fix]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        pass_filenames: false
+
       - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        pass_filenames: false
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0

CLAUDE.md

@@ -7,12 +7,24 @@ For detailed architecture and implementation patterns, see `specs/core-pipeline/
 ## Commands
 
 ```bash
+# Setup
+uv sync --all-extras        # Install all dependencies with lockfile
+
 # Development
-pip install -e ".[dev]"      # Install in editable mode
 pytest                        # Run all tests
+pytest --cov                  # Run tests with coverage
 mypy src/eventkit             # Type check
 ruff check src/               # Lint
 ruff format src/              # Format
+ruff format --check src/      # Check formatting without changing
+
+# Update dependencies
+uv lock                       # Update lockfile
+uv sync                       # Sync after lockfile update
+
+# Pre-commit (optional)
+pre-commit install            # Set up git hooks
+pre-commit run --all-files    # Run all hooks manually
 
 # Publishing
 python -m build                                      # Build distribution

CONTRIBUTING.md

@@ -257,7 +257,7 @@ def enqueue(self, event: RawEvent) -> None:
 ```python
 def get_partition_id(self, event: TypedEvent) -> int:
     """Route event to partition by identity hash.
-    
+
     Uses FNV-1a hash for good distribution. Events with same userId
     always route to same partition for ordered processing.
     """
@@ -492,16 +492,16 @@ N/A
 ```python
 def get_partition_id(self, event: TypedEvent) -> int:
     """Route event to partition by identity hash.
-    
+
     Uses FNV-1a hash of userId or anonymousId to ensure consistent
     routing. Events for same user always go to same partition.
-    
+
     Args:
         event: Typed event to route
-        
+
     Returns:
         Partition ID (0 to num_partitions-1)
-        
+
     Examples:
         >>> sequencer = Sequencer(num_partitions=16)
         >>> event = IdentifyEvent(userId="user_123", ...)