Update README.md

.env.example

@@ -0,0 +1,31 @@
+# Database
+DATABASE_URL=postgresql://housinghand:password@localhost:5432/housinghand
+DATABASE_POOL_SIZE=10
+DATABASE_MAX_OVERFLOW=20
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+CELERY_BROKER_URL=redis://localhost:6379/1
+CELERY_RESULT_BACKEND=redis://localhost:6379/2
+
+# API
+API_HOST=0.0.0.0
+API_PORT=8000
+API_DEBUG=true
+API_SECRET_KEY=change-me-in-production
+CORS_ORIGINS=http://localhost:3000,http://localhost:8000
+
+# HousingMind Ecosystem Integrations
+HOUSING_LENS_API_URL=http://localhost:8001/api/v1
+HOUSING_LENS_API_KEY=your-housing-lens-api-key
+HOUSING_EAR_API_URL=http://localhost:8002/api/v1
+HOUSING_EAR_API_KEY=your-housing-ear-api-key
+HOUSING_MIND_WEBHOOK_SECRET=your-webhook-secret
+
+# ML Model
+ML_MODEL_PATH=models/timeline_prediction.joblib
+ML_MODEL_VERSION=0.1.0
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FORMAT=json

.github/workflows/deploy.yml

@@ -0,0 +1,45 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: docker/Dockerfile
+          push: true
+          tags: |
+            ${{ secrets.REGISTRY_URL }}/housinghand:latest
+            ${{ secrets.REGISTRY_URL }}/housinghand:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run database migrations
+        run: |
+          echo "Run: alembic upgrade head"
+          echo "Migration step placeholder - configure with actual deployment target"
+
+      - name: Deploy notification
+        run: |
+          echo "Deployed HousingHand commit ${{ github.sha }}"

.github/workflows/model_training.yml

@@ -0,0 +1,50 @@
+name: Model Training
+
+on:
+  schedule:
+    - cron: "0 4 1 * *"  # First day of each month at 4:00 AM UTC
+  workflow_dispatch:
+
+jobs:
+  train:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgis/postgis:14-3.4
+        env:
+          POSTGRES_USER: housinghand
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: housinghand
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U housinghand"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements/ml.txt
+
+      - name: Train timeline prediction model
+        env:
+          DATABASE_URL: postgresql://housinghand:password@localhost:5432/housinghand
+        run: |
+          python scripts/train_model.py
+
+      - name: Upload model artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: timeline-model-${{ github.run_number }}
+          path: models/
+          retention-days: 90

.github/workflows/test.yml

@@ -0,0 +1,84 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgis/postgis:14-3.4
+        env:
+          POSTGRES_USER: housinghand
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: housinghand_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U housinghand"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements/test.txt
+          pip install -r requirements/ml.txt
+
+      - name: Run tests
+        env:
+          DATABASE_URL: postgresql://housinghand:password@localhost:5432/housinghand_test
+          REDIS_URL: redis://localhost:6379/0
+        run: |
+          pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install linters
+        run: |
+          pip install ruff black mypy
+
+      - name: Run ruff
+        run: ruff check src/ tests/
+
+      - name: Check formatting
+        run: black --check src/ tests/

.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+.env.production
+
+# Database
+*.db
+*.sqlite3
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# ML models
+models/*.pkl
+models/*.joblib
+*.model
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+docker-compose.override.yml
+
+# Logs
+*.log
+logs/
+
+# Redis dump
+dump.rdb

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HousingMind Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,78 @@
-# HousingHand
+# HousingHand
+
+Affordable Housing Development Pipeline Intelligence Platform for the HousingMind ecosystem.
+
+HousingHand tracks every affordable housing project from concept to certificate of occupancy, quantifying where development pipelines break down and connecting regulatory friction to real production outcomes. It creates the first comprehensive affordable housing development pipeline database, enabling stakeholders to predict timelines, identify bottlenecks, measure policy reform impact, and optimize portfolio performance.
+
+## Core Capabilities
+
+- **Pipeline Tracking** - Monitor affordable housing projects through all seven development stages
+- **Health Assessment** - Weighted scoring system evaluating timeline, budget, funding, risk, and team stability
+- **Bottleneck Intelligence** - Identify systematic barriers that delay or kill projects across jurisdictions
+- **Predictive Analytics** - Forecast project timelines using ML models trained on historical data and jurisdiction friction scores
+- **Policy Impact Measurement** - Quantify actual outcomes of regulatory reforms with statistical significance testing
+- **Portfolio Intelligence** - Aggregate views for PHAs, funders, cities, and policymakers
+
+## Tech Stack
+
+- **API**: Python 3.10+, FastAPI
+- **Database**: PostgreSQL 14+ with PostGIS
+- **ML/Analytics**: scikit-learn, pandas, numpy, scipy
+- **Task Queue**: Celery + Redis
+- **Testing**: pytest
+
+## Quick Start
+
+```bash
+# Clone and set up
+cp .env.example .env
+
+# Docker
+cd docker && docker compose up -d
+
+# Or local development
+python -m venv venv && source venv/bin/activate
+pip install -r requirements/dev.txt
+pip install -r requirements/ml.txt
+uvicorn src.api.app:app --reload
+```
+
+## Project Structure
+
+```
+src/
+  api/           # FastAPI application and endpoints
+  models/        # SQLAlchemy models (Project, FundingSource, Barrier, etc.)
+  analytics/     # Core analytics engine
+  ml/            # Timeline prediction ML model
+  integrations/  # HousingLens, HousingEar, HousingMind clients
+  data_collection/  # Developer portal, permit scrapers
+  database/      # Connection, queries, migrations
+  tasks/         # Celery async tasks
+  utils/         # Helper utilities
+tests/           # Test suite
+config/          # Settings and YAML configuration
+scripts/         # Database seeding, model training, reports
+docker/          # Docker and compose files
+docs/            # Documentation
+```
+
+## HousingMind Ecosystem Integration
+
+- **HousingLens** - Regulatory friction scores predict entitlement timelines
+- **HousingEar** - Policy monitoring feeds reform impact measurement
+- **HousingMind** - Query metadata tracks stakeholder engagement patterns
+
+## Documentation
+
+- [API Reference](docs/API.md)
+- [Data Model](docs/DATA_MODEL.md)
+- [Analytics Methodology](docs/ANALYTICS.md)
+- [Integration Guide](docs/INTEGRATION_GUIDE.md)
+- [Developer Portal](docs/DEVELOPER_PORTAL.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+
+## License
+
+©️ 2026 Zachary Urban 
+All Rights Reserved