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
```nix
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
```nix
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
```nix
cryptography            # Cryptographic primitives
libsasscompiler         # SASS compilation
```

#### Data and Markup
```nix
markdown                # Markdown processing
bleach                  # HTML sanitization
pydantic               # Data validation
lxml                   # XML processing
```

#### Database Support
```nix
psycopg2               # PostgreSQL adapter
# SQLite support built into Python
```

#### System Integration
```nix
openldap               # LDAP authentication
cyrus_sasl             # SASL authentication
```

## Development Setup

### Nix Environment
```bash
# Development shell
nix develop

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

### Build Environment
```nix
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```nix
users.users.bitpoll = {
  isSystemUser = true;
  group = "bitpoll";
  home = cfg.dataDir;
  createHome = true;
};
```

### systemd Hardening
```nix
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