docs: fix README to match actual project structure and tooling

- Replace pip commands with uv equivalents
- Fix run command from 'python -m src.main' to 'python -m polymarket_insider_tracker'
- Update project structure tree to reflect actual src/polymarket_insider_tracker/ layout

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -6,12 +6,12 @@ POSTGRES_USER=tracker
 POSTGRES_PASSWORD=dev_password
 
 # Constructed database URL (for application use)
-DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+DATABASE_URL=postgresql://tracker:dev_password@localhost:5432/polymarket_tracker
 
 # Redis Configuration
 REDIS_HOST=localhost
 REDIS_PORT=6379
-REDIS_URL=redis://${REDIS_HOST}:${REDIS_PORT}
+REDIS_URL=redis://localhost:6379
 
 # Optional: Development tool ports
 ADMINER_PORT=8080

README.md

@@ -126,13 +126,13 @@ docker compose up -d
 docker compose ps
 
 # Install Python dependencies
-pip install -e .
+uv sync --all-extras
 
 # Run database migrations
-alembic upgrade head
+uv run alembic upgrade head
 
 # Run the tracker
-python -m src.main
+uv run python -m polymarket_insider_tracker
 ```
 
 ### Docker Services
@@ -188,24 +188,16 @@ LIQUIDITY_IMPACT_THRESHOLD=0.02
 ```
 polymarket-insider-tracker/
 ├── src/
-│   ├── ingestor/           # Real-time market data ingestion
-│   │   ├── clob_client.py  # Polymarket CLOB API wrapper
-│   │   └── websocket.py    # WebSocket event handler
-│   ├── profiler/           # Wallet analysis
-│   │   ├── analyzer.py     # Core wallet profiling logic
-│   │   ├── chain.py        # Polygon blockchain client
-│   │   └── funding.py      # Funding chain tracer
-│   ├── detector/           # Anomaly detection engines
-│   │   ├── fresh_wallet.py
-│   │   ├── size_anomaly.py
-│   │   ├── sniper.py       # DBSCAN clustering
-│   │   └── scorer.py       # Composite risk scoring
-│   ├── alerter/            # Notification dispatch
-│   │   ├── formatter.py    # Alert message formatting
-│   │   └── dispatcher.py   # Multi-channel delivery
-│   └── storage/            # Persistence layer
-│       ├── models.py       # SQLAlchemy models
-│       └── repos.py        # Repository pattern
+│   └── polymarket_insider_tracker/
+│       ├── __main__.py     # CLI entry point
+│       ├── pipeline.py     # Core detection pipeline
+│       ├── ingestor/       # Real-time market data ingestion
+│       │   ├── clob_client.py  # Polymarket CLOB API wrapper
+│       │   └── websocket.py    # WebSocket event handler
+│       ├── profiler/       # Wallet analysis
+│       ├── detector/       # Anomaly detection engines
+│       ├── alerter/        # Notification dispatch
+│       └── storage/        # Persistence layer
 ├── tests/                  # Test suite
 ├── scripts/
 │   └── backtest.py         # Historical analysis
@@ -289,16 +281,16 @@ Contributions are welcome! Please read our Contributing Guide before submitting
 
 ```bash
 # Install dev dependencies
-pip install -e ".[dev]"
+uv sync --all-extras
 
 # Run tests
-pytest
+uv run pytest
 
 # Run linting
-ruff check src/
+uv run ruff check src/
 
 # Run type checking
-mypy src/
+uv run mypy src/
 ```
 
 ---

alembic/env.py

@@ -19,7 +19,7 @@ if config.config_file_name is not None:
 target_metadata = Base.metadata
 
 # Get database URL from environment variable or config
-database_url = os.environ.get("SQLALCHEMY_DATABASE_URL")
+database_url = os.environ.get("DATABASE_URL")
 if database_url:
     config.set_main_option("sqlalchemy.url", database_url)
 

alembic/versions/20260104_0000_initial_schema.py

@@ -5,16 +5,16 @@ Revises:
 Create Date: 2026-01-04 00:00:00.000000+00:00
 """
 
-from typing import Sequence, Union
+from collections.abc import Sequence
 
 import sqlalchemy as sa
 from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = "001_initial"
-down_revision: Union[str, None] = None
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
 
 
 def upgrade() -> None:

docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3.8"
-
 services:
   postgres:
     image: postgres:15

src/polymarket_insider_tracker/ingestor/metadata_sync.py

@@ -11,7 +11,7 @@ import logging
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 
 from redis.asyncio import Redis
 
@@ -27,7 +27,7 @@ DEFAULT_CACHE_TTL_SECONDS = 600  # 10 minutes
 DEFAULT_REDIS_KEY_PREFIX = "polymarket:market:"
 
 
-class SyncState(str, Enum):
+class SyncState(StrEnum):
     """State of the metadata synchronizer."""
 
     STOPPED = "stopped"

src/polymarket_insider_tracker/ingestor/models.py

@@ -86,7 +86,7 @@ class Orderbook:
     bids: tuple[OrderbookLevel, ...]
     asks: tuple[OrderbookLevel, ...]
     tick_size: Decimal
-    timestamp: datetime = field(default_factory=datetime.utcnow)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
 
     @classmethod
     def from_clob_orderbook(cls, orderbook: Any) -> "Orderbook":

src/polymarket_insider_tracker/ingestor/websocket.py

@@ -9,8 +9,9 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Any
 
-import websockets
 from websockets.asyncio.client import ClientConnection
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import ConnectionClosed
 
 from polymarket_insider_tracker.ingestor.models import TradeEvent
 
@@ -156,7 +157,7 @@ class TradeStreamHandler:
         await self._set_state(ConnectionState.CONNECTING)
 
         try:
-            ws = await websockets.connect(
+            ws = await ws_connect(
                 self._host,
                 ping_interval=self._ping_interval,
                 ping_timeout=self._ping_interval * 2,
@@ -227,7 +228,7 @@ class TradeStreamHandler:
                 else:
                     logger.debug("Received binary message (%d bytes)", len(message))
 
-        except websockets.ConnectionClosed as e:
+        except ConnectionClosed as e:
             logger.warning("Connection closed: %s", e)
             raise
         except Exception as e:
@@ -284,7 +285,7 @@ class TradeStreamHandler:
             while self._running:
                 try:
                     await self._listen(self._ws)
-                except (websockets.ConnectionClosed, Exception) as e:
+                except (ConnectionClosed, Exception) as e:
                     if not self._running:
                         break
 

src/polymarket_insider_tracker/pipeline.py

@@ -11,7 +11,7 @@ import contextlib
 import logging
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 from typing import TYPE_CHECKING
 
 from redis.asyncio import Redis
@@ -43,7 +43,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class PipelineState(str, Enum):
+class PipelineState(StrEnum):
     """Pipeline lifecycle states."""
 
     STOPPED = "stopped"

tests/ingestor/test_websocket.py

@@ -231,7 +231,10 @@ class TestTradeStreamHandler:
         mock_ws = AsyncMock()
         mock_ws.send = AsyncMock()
 
-        with patch("websockets.connect", AsyncMock(return_value=mock_ws)):
+        with patch(
+            "polymarket_insider_tracker.ingestor.websocket.ws_connect",
+            AsyncMock(return_value=mock_ws),
+        ):
             ws = await handler._connect()
 
             assert ws is mock_ws
@@ -333,7 +336,10 @@ class TestTradeStreamHandlerIntegration:
 
         mock_ws = MockWebSocket(handler, trade_message)
 
-        with patch("websockets.connect", AsyncMock(return_value=mock_ws)):
+        with patch(
+            "polymarket_insider_tracker.ingestor.websocket.ws_connect",
+            AsyncMock(return_value=mock_ws),
+        ):
             # Run with timeout to prevent hanging
             try:
                 await asyncio.wait_for(handler.start(), timeout=1.0)