bitpoll-nix/memory-bank/techContext.md

Tech Context: Bitpoll Nix Flake

Technology Stack

Core Technologies

• Nix/NixOS: Package management and system configuration
• Django: Web framework (Bitpoll's foundation)
• Python 3: Runtime environment
• SQLite: Default database (PostgreSQL supported)
• systemd: Service management

Nix Ecosystem

• Flakes: Modern Nix package management
• nixpkgs: Package repository (NixOS 25.05)
• flake-utils: Cross-platform utilities
• NixOS Modules: System service configuration

Python Dependencies

Core Django Stack

django                    # Web framework
django-encrypted-model-fields  # Data encryption
django-simple-csp        # Content Security Policy
django-markdownify       # Markdown processing
django-pipeline          # Asset pipeline
django-friendly-tag-loader  # Template utilities
django-token-bucket      # Rate limiting
django-widget-tweaks     # Form widgets

Calendar and Date Handling

caldav                   # CalDAV protocol support
icalendar               # iCalendar format handling
python-dateutil         # Date parsing utilities
pytz                    # Timezone handling
vobject                 # vCard/vCalendar objects
recurring-ical-events  # Recurring event processing

Security and Crypto

cryptography            # Cryptographic primitives
libsasscompiler         # SASS compilation

Data and Markup

markdown                # Markdown processing
bleach                  # HTML sanitization
pydantic               # Data validation
lxml                   # XML processing

Database Support

psycopg2               # PostgreSQL adapter
# SQLite support built into Python

System Integration

openldap               # LDAP authentication
cyrus_sasl             # SASL authentication

Development Setup

Nix Environment

# Development shell
nix develop

# Available tools in dev shell:
- python3
- pip
- virtualenv
- gettext (internationalization)
- openldap
- cyrus_sasl

Build Environment

nativeBuildInputs = [
  gettext      # Message compilation
  pythonEnv    # Python with packages
];

buildInputs = [
  openldap     # LDAP support
  cyrus_sasl   # SASL support
];

Technical Constraints

Nix-Specific Constraints

• Reproducible Builds: All dependencies must be pinned
• Pure Builds: No network access during build
• FHS Compliance: Must work within Nix store structure
• Cross-platform: Support Linux and macOS development

Django Constraints

• Settings Management: Must handle production vs development
• Static Files: Proper collection and serving
• Database Migrations: Automatic handling required
• Secret Management: Secure key handling

System Constraints

• User Isolation: Dedicated system user required
• File Permissions: Proper ownership and access control
• Service Management: systemd integration
• Security Hardening: Comprehensive restrictions

Dependencies Management

Package Resolution Strategy

1. nixpkgs packages: Use when available and compatible
2. pip installation: For packages not in nixpkgs
3. Custom patches: When upstream packages need fixes
4. Version pinning: Ensure reproducible builds

Python Path Management

# Build-time PYTHONPATH
export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:$PYTHONPATH

# Runtime PYTHONPATH (in wrapper scripts)
export PYTHONPATH=$out/lib/python3.12/site-packages:$out/share/bitpoll:$PYTHONPATH

Dependency Installation Process

1. Core packages via python3.withPackages
2. Missing packages via pip to $out/lib/python3.12/site-packages
3. PYTHONPATH configuration in wrapper scripts
4. Runtime environment variable setup

Tool Usage Patterns

Nix Commands

# Build package
nix build

# Run development server
nix run

# Run management commands
nix run .#bitpoll-manage -- <command>

# Enter development shell
nix develop

# Check flake
nix flake check

Django Management

# Database operations
bitpoll-manage migrate
bitpoll-manage createsuperuser
bitpoll-manage collectstatic

# Development
bitpoll-manage runserver
bitpoll-manage shell

# Maintenance
bitpoll-manage check
bitpoll-manage generate_encryption_key

System Operations

# NixOS deployment
sudo nixos-rebuild switch --flake .#hostname

# Service management
systemctl status bitpoll
systemctl restart bitpoll
journalctl -u bitpoll

Configuration Management

Build-time Configuration

• settings_local.py: Generated at build time
• Default values: Secure production defaults
• Path configuration: Nix store and data directory paths

Deploy-time Configuration

• NixOS options: Service configuration
• Module parameters: Port, host, data directory
• Security settings: User, permissions, hardening

Runtime Configuration

• Environment variables: Secret overrides
• Secret files: External key management
• Dynamic settings: Runtime-generated values

Security Architecture

User Isolation

users.users.bitpoll = {
  isSystemUser = true;
  group = "bitpoll";
  home = cfg.dataDir;
  createHome = true;
};

systemd Hardening

serviceConfig = {
  NoNewPrivileges = true;
  PrivateTmp = true;
  ProtectSystem = "strict";
  ProtectHome = true;
  ReadWritePaths = [ cfg.dataDir ];
  PrivateDevices = true;
  ProtectKernelTunables = true;
  ProtectKernelModules = true;
  ProtectControlGroups = true;
};

File System Security

• Data directory: /var/lib/bitpoll with restricted access
• Read-only system: Most filesystem read-only
• Temporary isolation: Private temporary directories
• Device restrictions: No device access

Performance Considerations

Build Performance

• Cached builds: Nix store caching
• Incremental builds: Only rebuild changed components
• Parallel builds: Multi-core build support

Runtime Performance

• Python optimization: Compiled bytecode
• Static file serving: Efficient asset delivery
• Database optimization: Proper indexing and queries
• Memory management: Controlled resource usage

Deployment Performance

• Atomic updates: Zero-downtime deployments
• Rollback capability: Instant rollback to previous versions
• Service restart: Graceful restart handling

Integration Points

External Systems

• LDAP: Authentication integration
• CalDAV: Calendar system integration
• Email: Notification system
• Reverse Proxy: nginx/traefik integration

Monitoring and Logging

• systemd journals: Centralized logging
• Django logging: Application-level logs
• Health checks: Service monitoring
• Metrics collection: Performance monitoring

Version Management

Upstream Tracking

• Bitpoll version: master branch (commit 4a3e6a5)
• nixpkgs version: NixOS 25.05
• Python version: 3.x from nixpkgs
• Django version: Latest from nixpkgs

Update Strategy

• Pin specific commits: Reproducible builds
• Test before update: Comprehensive testing
• Gradual rollout: Staged deployment
• Rollback plan: Quick recovery capability