docs: add comprehensive README files across the codebase

README.md

@@ -1,9 +1,143 @@
-django-htk
-==========
+# HTK: Django Hacktoolkit
 
-A set of apps, utilities, middlewares, etc for Django
+A comprehensive Django framework providing reusable apps, utilities, and third-party integrations for rapid development. Designed for hackathons and production applications.
 
-Used/embedded in <https://github.com/hacktoolkit/htk-django-skeleton
+## Overview
 
-Author: Jonathan Tsai <https://github.com/jontsai>
-License: MIT
+HTK includes:
+
+- **[Reusable Django Apps](./apps/README.md)** - Pre-built apps for accounts, organizations, payments, messaging, and more
+- **[Third-Party Integrations](./lib/README.md)** - Ready-to-use connectors for 45+ external services (Stripe, Google, AWS, Slack, etc.)
+- **[Utility Modules](./utils/README.md)** - Common patterns for caching, text processing, APIs, and data handling
+- **[API Helpers](./api/README.md)** - Tools for building REST APIs with DataTables support
+- **[Form Utilities](./forms/README.md)** - Base form classes and validators
+- **[Decorators](./decorators/README.md)** - Django and function decorators for common tasks
+- **[Models & Fields](./models/README.md)** - Abstract models and custom Django fields
+- **[Middleware](./middleware/README.md)** - Request/response processing utilities
+
+## Quick Start
+
+### Using HTK Apps
+
+HTK provides pre-built Django apps that can be installed and configured in your project:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'htk.apps.accounts',
+    'htk.apps.organizations',
+    'htk.apps.stripe_lib',
+    # ... more apps
+]
+```
+
+### Common Patterns
+
+**Caching objects:**
+```python
+from htk.cache.classes import CacheableObject
+
+class UserFollowingCache(CacheableObject):
+    def get_cache_key_suffix(self):
+        return f'user_{self.user_id}_following'
+```
+
+**User authentication:**
+```python
+from htk.apps.accounts.backends import HtkUserTokenAuthBackend
+from htk.apps.accounts.utils.auth import login_authenticated_user
+```
+
+**API endpoints:**
+```python
+from htk.api.utils import json_response_form_error, get_object_or_json_error
+```
+
+## Key Features
+
+### Accounts & Authentication
+- User registration and email verification
+- Social authentication backends (OAuth2 support)
+- User profiles and email management
+- Token-based authentication
+
+### Payments & Billing
+- Stripe integration (customers, subscriptions, charges)
+- Quote/Invoice system (CPQ)
+- Payment tracking and history
+
+### Organizations
+- Multi-org support with roles and permissions
+- Org invitations and member management
+- Permission-based access control
+
+### Messaging & Notifications
+- Email notifications
+- Slack integration
+- Conversation/threading support
+
+### Utilities
+- Text processing (formatting, translation, sanitization)
+- Caching decorators and schemes
+- CSV/PDF generation
+- QR codes
+- Geolocation and distance calculations
+- Timezone handling
+
+### Third-Party Services
+See [lib/README.md](./lib/README.md) for details on 45+ integrations including:
+- Cloud: AWS S3, Google Cloud
+- Communication: Slack, Discord, Gmail, Twilio
+- Data: Airtable, Stripe, Shopify, Zuora
+- Analytics: Iterable, Mixpanel
+- Location: Google Maps, Mapbox, Zillow
+- Search: Elasticsearch integration patterns
+
+## Project Structure
+
+```
+htk/
+├── apps/              # Pre-built Django apps
+├── lib/               # Third-party service integrations
+├── utils/             # Common utilities and helpers
+├── models/            # Abstract models and field types
+├── forms/             # Base form classes
+├── api/               # REST API utilities
+├── decorators/        # Function and class decorators
+├── middleware/        # Request/response processing
+├── cache/             # Caching framework
+├── constants/         # Project-wide constants
+├── extensions/        # Django extensions
+├── templates/         # Reusable templates
+└── templatetags/      # Custom template filters and tags
+```
+
+## Module Documentation
+
+For detailed information about each module, see:
+
+- **[Apps](./apps/README.md)** - Reusable Django application packages
+- **[Libraries](./lib/README.md)** - Third-party service integrations
+- **[Utilities](./utils/README.md)** - Helper functions and utilities
+- **[API](./api/README.md)** - REST API patterns and tools
+- **[Cache](./cache/README.md)** - Caching framework and patterns
+- **[Forms](./forms/README.md)** - Form utilities and base classes
+- **[Decorators](./decorators/README.md)** - Function and class decorators
+- **[Models](./models/README.md)** - Abstract models and custom fields
+- **[Validators](./validators/README.md)** - Validation utilities
+
+## Use Cases
+
+**Hackathons:** Rapidly build production-quality features with pre-built apps and integrations.
+
+**SaaS Applications:** Multi-organization support, billing, and user management out of the box.
+
+**E-commerce:** Stripe payments, inventory management, order processing.
+
+**Content Platforms:** User accounts, organizations, messaging, notifications.
+
+**Marketplaces:** Payment processing, user profiles, organization support.
+
+## Contributing
+
+HTK is designed to be extended. Create custom apps that inherit from abstract base classes and add your own business logic.

admin/README.md

@@ -0,0 +1,43 @@
+# Django Admin Utilities
+
+Custom admin display and customization utilities.
+
+## Quick Start
+
+```python
+from htk.admin.decorators import django_admin_bool_field
+
+@django_admin_bool_field('is_active')
+def is_active_display(obj):
+    return obj.is_active
+is_active_display.short_description = 'Active'
+
+class UserAdmin(admin.ModelAdmin):
+    list_display = ['username', is_active_display]
+```
+
+## Boolean Field Display
+
+Display boolean fields as green checkmarks or red X marks in admin list view:
+
+```python
+from htk.admin.decorators import django_admin_bool_field
+
+class ProductAdmin(admin.ModelAdmin):
+    list_display = ['name', is_available, is_featured]
+
+    @django_admin_bool_field('is_available')
+    def is_available(obj):
+        return obj.is_available
+
+    @django_admin_bool_field('is_featured')
+    def is_featured(obj):
+        return obj.is_featured
+```
+
+## Configuration
+
+```python
+# settings.py
+ADMIN_SITE_HEADER = 'My Admin'
+```

admintools/README.md

@@ -0,0 +1,83 @@
+# Admin Tools
+
+Advanced admin functionality including user impersonation and company user management.
+
+## Quick Start
+
+```python
+from htk.admintools.decorators import company_officer_required, company_employee_required
+from htk.admintools.utils import is_allowed_to_emulate_users, request_emulate_user
+
+# Protect views for company officers
+@company_officer_required
+def officer_dashboard(request):
+    return render(request, 'officer_dashboard.html')
+
+# Protect views for company employees
+@company_employee_required
+def employee_portal(request):
+    return render(request, 'employee_portal.html')
+```
+
+## User Impersonation
+
+Allow admins to emulate other users for testing:
+
+```python
+from htk.admintools.utils import is_allowed_to_emulate_users, request_emulate_user
+
+# Check if user can emulate others
+if is_allowed_to_emulate_users(request.user):
+    # Allow user emulation in admin panel
+    pass
+
+# Emulate a specific user
+request_emulate_user(request, original_user, target_user)
+```
+
+## Company User Management
+
+Check company affiliation and roles:
+
+```python
+from htk.admintools.models import company_officer_required, is_company_officer, is_company_employee
+
+# Check officer status
+if is_company_officer(user):
+    # User is a company officer
+    pass
+
+# Check employee status
+if is_company_employee(user):
+    # User is a company employee
+    pass
+
+# Check email domain
+if user.has_company_email_domain():
+    # User has company email
+    pass
+```
+
+## Company Data Lookups
+
+Get mappings of company users:
+
+```python
+from htk.admintools.utils import get_company_officers_id_email_map, get_company_employees_id_email_map
+
+# Get officers mapping
+officers = get_company_officers_id_email_map()
+# Returns: {user_id: email, ...}
+
+# Get employees mapping
+employees = get_company_employees_id_email_map()
+# Returns: {user_id: email, ...}
+```
+
+## Configuration
+
+```python
+# settings.py
+# Enable company user features
+COMPANY_ADMIN_ENABLED = True
+```

admintools/constants/README.md

@@ -0,0 +1,65 @@
+# Admin Tools Constants
+
+## Overview
+
+This module provides configuration constants for the admin tools dashboard and user emulation features.
+
+## Configuration Settings
+
+```python
+from htk.admintools.constants import (
+    HTK_COMPANY_EMAIL_DOMAINS,
+    HTK_COMPANY_OFFICER_EMAILS,
+    HTK_COMPANY_EMPLOYEE_EMAILS,
+    HTK_EMULATE_USER_COOKIE_EXPIRATION_MINUTES,
+    HTK_ADMINTOOLS_TODOS_CONFIGS
+)
+
+# Email domains that identify company employees
+HTK_COMPANY_EMAIL_DOMAINS = ()  # e.g. ('company.com', 'internal.company.com')
+
+# Email addresses of company officers
+HTK_COMPANY_OFFICER_EMAILS = ()  # e.g. ('ceo@company.com', 'cto@company.com')
+
+# Email addresses of all company employees
+HTK_COMPANY_EMPLOYEE_EMAILS = ()  # Subset of HTK_COMPANY_OFFICER_EMAILS
+
+# Session timeout for user emulation (minutes)
+HTK_EMULATE_USER_COOKIE_EXPIRATION_MINUTES = 15
+
+# List of admin todo configurations
+HTK_ADMINTOOLS_TODOS_CONFIGS = []
+```
+
+## Dashboard Constants
+
+```python
+from htk.admintools.constants import (
+    PULSE_RECENTLY_EDITED_PROFILES_LIMIT,
+    PULSE_RECENTLY_JOINED_USERS_LIMIT,
+    PULSE_RECENT_LOGINS_LIMIT,
+    PULSE_STATS_PRECISION,
+    ADMINTOOLS_USER_PAGE_SIZE
+)
+
+# Dashboard data limits
+PULSE_RECENTLY_EDITED_PROFILES_LIMIT = 50
+PULSE_RECENTLY_JOINED_USERS_LIMIT = 50
+PULSE_RECENT_LOGINS_LIMIT = 50
+
+# Decimal precision for statistics
+PULSE_STATS_PRECISION = 4
+
+# User list pagination
+ADMINTOOLS_USER_PAGE_SIZE = 25
+```
+
+## Customization
+
+Override these settings in `settings.py`:
+
+```python
+HTK_COMPANY_EMAIL_DOMAINS = ('acme.com', 'acme.internal')
+HTK_EMULATE_USER_COOKIE_EXPIRATION_MINUTES = 30
+PULSE_RECENTLY_EDITED_PROFILES_LIMIT = 100
+```