docs: add @doc to public functions in EmailSync, Validations, and Senders

Document public API functions with @doc for better tooling support: - EmailSync Changes: sync_user_email_to_member, sync_member_email_to_user - Validations: email_not_used_by_other_member, email_not_used_by_other_user - Senders: send_new_user_confirmation_email, send_password_reset_email
refactor: split long sort handler into smaller functions
2025-11-10 17:03:54 +01:00 · 2025-11-10 17:03:50 +01:00 · 2025-11-10 17:03:43 +01:00 · 2025-11-10 17:03:38 +01:00 · 2025-11-10 17:03:32 +01:00 · 2025-11-10 17:03:19 +01:00
33 changed files with 5974 additions and 67 deletions
--- a/.credo.exs
+++ b/.credo.exs
@ -158,11 +158,11 @@
          {Credo.Check.Warning.UnusedRegexOperation, []},
          {Credo.Check.Warning.UnusedStringOperation, []},
          {Credo.Check.Warning.UnusedTupleOperation, []},
-          {Credo.Check.Warning.WrongTestFileExtension, []}
+          {Credo.Check.Warning.WrongTestFileExtension, []},
+          # Module documentation check (enabled after adding @moduledoc to all modules)
+          {Credo.Check.Readability.ModuleDoc, []}
        ],
        disabled: [
-          # Checks disabled by the Mitgliederverwaltung Team
-          {Credo.Check.Readability.ModuleDoc, []},
          #
          # Checks scheduled for next check update (opt-in for now)
          {Credo.Check.Refactor.UtcNowTruncate, []},
--- a/CODE_GUIDELINES.md
+++ b/CODE_GUIDELINES.md
--- a/README.md
+++ b/README.md
@ -161,27 +161,33 @@ Now you can log in to Mila via OIDC!

 ## 🏗️ Architecture

- **Backend:** Elixir, Phoenix, LiveView, Ash Framework  
- **Frontend:** Phoenix LiveView + DaisyUI + Heroicons  
- **Database:** PostgreSQL (via AshPostgres)  
- **Auth:** AshAuthentication (OIDC + password strategy)  
- **Mail:** Swoosh  
- **i18n:** Gettext  
+**Tech Stack Overview:**
+- **Backend:** Elixir + Phoenix + Ash Framework  
+- **Frontend:** Phoenix LiveView + Tailwind CSS + DaisyUI  
+- **Database:** PostgreSQL  
+- **Auth:** AshAuthentication (OIDC + password)

-Code structure:  
- `lib/mv/` — core Ash resources/domains (`Accounts`, `Membership`)  
+**Code Structure:**
+- `lib/accounts/` & `lib/membership/` — Ash resources and domains
 - `lib/mv_web/` — Phoenix controllers, LiveViews, components  
- `assets/` — frontend assets (Tailwind, JS, etc.)  
+- `assets/` — Tailwind, JavaScript, static files
+
+📚 **Full tech stack details:** See [`CODE_GUIDELINES.md`](CODE_GUIDELINES.md)  
+📖 **Implementation history:** See [`docs/development-progress-log.md`](docs/development-progress-log.md)  
+🗄️ **Database schema:** See [`docs/database-schema-readme.md`](docs/database-schema-readme.md)  

 ## 🧑‍💻 Development

-Useful `just` commands:  
- `just run` — start DB, Mailcrab, Rauthy, app  
- `just test` — run tests  
- `just lint` — run code style checks (credo, formatter)  
- `just audit` — run security audits  
- `just reset-database` — reset local DB  
- `just regen-migrations <name>` — regenerate migrations  
+**Common commands:**
+```bash
+just run                      # Start full dev environment
+just test                     # Run test suite
+just lint                     # Code style checks
+just audit                    # Security audits
+just reset-database           # Reset local DB
+```
+
+📚 **Full development guidelines:** See [`CODE_GUIDELINES.md`](CODE_GUIDELINES.md)  

 ## 📦 Production Deployment

--- a/docs/database-schema-readme.md
+++ b/docs/database-schema-readme.md
@ -0,0 +1,392 @@
+# Database Schema Documentation
+
+## Overview
+
+This document provides a comprehensive overview of the Mila Membership Management System database schema.
+
+## Quick Links
+
+- **DBML File:** [`database_schema.dbml`](./database_schema.dbml)
+- **Visualize Online:** 
+  - [dbdiagram.io](https://dbdiagram.io) - Upload the DBML file
+  - [dbdocs.io](https://dbdocs.io) - Generate interactive documentation
+
+## Schema Statistics
+
+| Metric | Count |
+|--------|-------|
+| **Tables** | 5 |
+| **Domains** | 2 (Accounts, Membership) |
+| **Relationships** | 3 |
+| **Indexes** | 15+ |
+| **Triggers** | 1 (Full-text search) |
+
+## Tables Overview
+
+### Accounts Domain
+
+#### `users`
+- **Purpose:** User authentication and session management
+- **Rows (Estimated):** Low to Medium (typically 10-50% of members)
+- **Key Features:** 
+  - Dual authentication (Password + OIDC)
+  - Optional 1:1 link to members
+  - Email as source of truth when linked
+
+#### `tokens`
+- **Purpose:** JWT token storage for AshAuthentication
+- **Rows (Estimated):** Medium to High (multiple tokens per user)
+- **Key Features:**
+  - Token lifecycle management
+  - Revocation support
+  - Multiple token purposes
+
+### Membership Domain
+
+#### `members`
+- **Purpose:** Club member master data
+- **Rows (Estimated):** High (core entity)
+- **Key Features:**
+  - Complete member profile
+  - Full-text search via tsvector
+  - Bidirectional email sync with users
+  - Flexible address and contact data
+
+#### `properties`
+- **Purpose:** Dynamic custom member attributes
+- **Rows (Estimated):** Variable (N per member)
+- **Key Features:**
+  - Union type value storage (JSONB)
+  - Multiple data types supported
+  - One property per type per member
+
+#### `property_types`
+- **Purpose:** Schema definitions for custom properties
+- **Rows (Estimated):** Low (admin-defined)
+- **Key Features:**
+  - Type definitions
+  - Immutable and required flags
+  - Centralized property management
+
+## Key Relationships
+
+```
+User (0..1) ←→ (0..1) Member
+       ↓
+    Tokens (N)
+
+Member (1) → (N) Properties
+                    ↓
+              PropertyType (1)
+```
+
+### Relationship Details
+
+1. **User ↔ Member (Optional 1:1, both sides optional)**
+   - A User can have 0 or 1 Member (`user.member_id` can be NULL)
+   - A Member can have 0 or 1 User (optional `has_one` relationship)
+   - Both entities can exist independently
+   - Email synchronization when linked (User.email is source of truth)
+   - `ON DELETE SET NULL` on user side (User preserved when Member deleted)
+
+2. **Member → Properties (1:N)**
+   - One member, many properties
+   - `ON DELETE CASCADE` - properties deleted with member
+   - Composite unique constraint (member_id, property_type_id)
+
+3. **Property → PropertyType (N:1)**
+   - Properties reference type definition
+   - `ON DELETE RESTRICT` - cannot delete type if in use
+   - Type defines data structure
+
+## Important Business Rules
+
+### Email Synchronization
+- **User.email** is the source of truth when linked
+- On linking: Member.email ← User.email (overwrite)
+- After linking: Changes sync bidirectionally
+- Validation prevents email conflicts
+
+### Authentication Strategies
+- **Password:** Email + hashed_password
+- **OIDC:** Email + oidc_id (Rauthy provider)
+- At least one method required per user
+
+### Member Constraints
+- First name and last name required (min 1 char)
+- Email unique, validated format (5-254 chars)
+- Birth date cannot be in future
+- Join date cannot be in future
+- Exit date must be after join date
+- Phone: `+?[0-9\- ]{6,20}`
+- Postal code: 5 digits
+
+### Property System
+- Maximum one property per type per member
+- Value stored as union type in JSONB
+- Supported types: string, integer, boolean, date, email
+- Types can be marked as immutable or required
+
+## Indexes
+
+### Performance Indexes
+
+**members:**
+- `search_vector` (GIN) - Full-text search
+- `email` - Email lookups
+- `last_name` - Name sorting
+- `join_date` - Date filtering
+- `paid` (partial) - Payment status queries
+
+**properties:**
+- `member_id` - Member property lookups
+- `property_type_id` - Type-based queries
+- Composite `(member_id, property_type_id)` - Uniqueness
+
+**tokens:**
+- `subject` - User token lookups
+- `expires_at` - Token cleanup
+- `purpose` - Purpose-based queries
+
+**users:**
+- `email` (unique) - Login lookups
+- `oidc_id` (unique) - OIDC authentication
+- `member_id` (unique) - Member linkage
+
+## Full-Text Search
+
+### Implementation
+- **Trigger:** `members_search_vector_trigger()`
+- **Function:** Automatically updates `search_vector` on INSERT/UPDATE
+- **Index Type:** GIN (Generalized Inverted Index)
+
+### Weighted Fields
+- **Weight A (highest):** first_name, last_name
+- **Weight B:** email, notes
+- **Weight C:** birth_date, phone_number, city, street, house_number, postal_code
+- **Weight D (lowest):** join_date, exit_date
+
+### Usage Example
+```sql
+SELECT * FROM members 
+WHERE search_vector @@ to_tsquery('simple', 'john & doe');
+```
+
+## Database Extensions
+
+### Required PostgreSQL Extensions
+
+1. **uuid-ossp**
+   - Purpose: UUID generation functions
+   - Used for: `gen_random_uuid()`, `uuid_generate_v7()`
+
+2. **citext**
+   - Purpose: Case-insensitive text type
+   - Used for: `users.email` (case-insensitive email matching)
+
+### Installation
+```sql
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "citext";
+```
+
+## Migration Strategy
+
+### Ash Migrations
+This project uses Ash Framework's migration system:
+
+```bash
+# Generate new migration
+mix ash.codegen --name add_new_feature
+
+# Apply migrations
+mix ash.setup
+
+# Rollback migrations
+mix ash_postgres.rollback -n 1
+```
+
+### Migration Files Location
+```
+priv/repo/migrations/
+├── 20250421101957_initialize_extensions_1.exs
+├── 20250528163901_initial_migration.exs
+├── 20250617090641_member_fields.exs
+├── 20250620110850_add_accounts_domain.exs
+├── 20250912085235_AddSearchVectorToMembers.exs
+├── 20250926180341_add_unique_email_to_members.exs
+└── 20251016130855_add_constraints_for_user_member_and_property.exs
+```
+
+## Data Integrity
+
+### Foreign Key Behaviors
+
+| Relationship | On Delete | Rationale |
+|--------------|-----------|-----------|
+| `users.member_id → members.id` | SET NULL | Preserve user account when member deleted |
+| `properties.member_id → members.id` | CASCADE | Delete properties with member |
+| `properties.property_type_id → property_types.id` | RESTRICT | Prevent deletion of types in use |
+
+### Validation Layers
+
+1. **Database Level:**
+   - CHECK constraints
+   - NOT NULL constraints
+   - UNIQUE indexes
+   - Foreign key constraints
+
+2. **Application Level (Ash):**
+   - Custom validators
+   - Email format validation (EctoCommons.EmailValidator)
+   - Business rule validation
+   - Cross-entity validation
+
+3. **UI Level:**
+   - Client-side form validation
+   - Real-time feedback
+   - Error messages
+
+## Performance Considerations
+
+### Query Patterns
+
+**High Frequency:**
+- Member search (uses GIN index on search_vector)
+- Member list with filters (uses indexes on join_date, paid)
+- User authentication (uses unique index on email/oidc_id)
+- Property lookups by member (uses index on member_id)
+
+**Medium Frequency:**
+- Member CRUD operations
+- Property updates
+- Token validation
+
+**Low Frequency:**
+- PropertyType management
+- User-Member linking
+- Bulk operations
+
+### Optimization Tips
+
+1. **Use indexes:** All critical query paths have indexes
+2. **Preload relationships:** Use Ash's `load` to avoid N+1
+3. **Pagination:** Use keyset pagination (configured by default)
+4. **Partial indexes:** `members.paid` index only non-NULL values
+5. **Search optimization:** Full-text search via tsvector, not LIKE
+
+## Visualization
+
+### Using dbdiagram.io
+
+1. Visit [https://dbdiagram.io](https://dbdiagram.io)
+2. Click "Import" → "From file"
+3. Upload `database_schema.dbml`
+4. View interactive diagram with relationships
+
+### Using dbdocs.io
+
+1. Install dbdocs CLI: `npm install -g dbdocs`
+2. Generate docs: `dbdocs build database_schema.dbml`
+3. View generated documentation
+
+### VS Code Extension
+
+Install "DBML Language" extension to view/edit DBML files with:
+- Syntax highlighting
+- Inline documentation
+- Error checking
+
+## Security Considerations
+
+### Sensitive Data
+
+**Encrypted:**
+- `users.hashed_password` (bcrypt)
+
+**Should Not Log:**
+- hashed_password
+- tokens (jti, purpose, extra_data)
+
+**Personal Data (GDPR):**
+- All member fields (name, email, birth_date, address)
+- User email
+- Token subject
+
+### Access Control
+
+- Implement through Ash policies
+- Row-level security considerations for future
+- Audit logging for sensitive operations
+
+## Backup Recommendations
+
+### Critical Tables (Priority 1)
+- `members` - Core business data
+- `users` - Authentication data
+- `property_types` - Schema definitions
+
+### Important Tables (Priority 2)
+- `properties` - Member custom data
+- `tokens` - Can be regenerated but good to backup
+
+### Backup Strategy
+```bash
+# Full database backup
+pg_dump -Fc mv_prod > backup_$(date +%Y%m%d).dump
+
+# Restore
+pg_restore -d mv_prod backup_20251110.dump
+```
+
+## Testing
+
+### Test Database
+- Separate test database: `mv_test`
+- Sandbox mode via Ecto.Adapters.SQL.Sandbox
+- Reset between tests
+
+### Seed Data
+```bash
+# Load seed data
+mix run priv/repo/seeds.exs
+```
+
+## Future Considerations
+
+### Potential Additions
+
+1. **Audit Log Table**
+   - Track changes to members
+   - Compliance and history tracking
+
+2. **Payment Tracking**
+   - Payment history table
+   - Transaction records
+   - Fee calculation
+
+3. **Document Storage**
+   - Member documents/attachments
+   - File metadata table
+
+4. **Email Queue**
+   - Outbound email tracking
+   - Delivery status
+
+5. **Roles & Permissions**
+   - User roles (admin, treasurer, member)
+   - Permission management
+
+## Resources
+
+- **Ash Framework:** [https://hexdocs.pm/ash](https://hexdocs.pm/ash)
+- **AshPostgres:** [https://hexdocs.pm/ash_postgres](https://hexdocs.pm/ash_postgres)
+- **DBML Specification:** [https://dbml.dbdiagram.io](https://dbml.dbdiagram.io)
+- **PostgreSQL Docs:** [https://www.postgresql.org/docs/](https://www.postgresql.org/docs/)
+
+---
+
+**Last Updated:** 2025-11-10  
+**Schema Version:** 1.0  
+**Database:** PostgreSQL 17.6 (dev) / 16 (prod)
+
--- a/docs/database_schema.dbml
+++ b/docs/database_schema.dbml
@ -0,0 +1,329 @@
+// Mila - Membership Management System
+// Database Schema Documentation
+// 
+// This file can be used with:
+// - https://dbdiagram.io
+// - https://dbdocs.io
+// - VS Code Extensions: "DBML Language" or "dbdiagram.io"
+//
+// Version: 1.0
+// Last Updated: 2025-11-10
+
+Project mila_membership_management {
+  database_type: 'PostgreSQL'
+  Note: '''
+    # Mila Membership Management System
+    
+    A membership management application for small to mid-sized clubs.
+    
+    ## Key Features:
+    - User authentication (OIDC + Password)
+    - Member management with flexible custom properties
+    - Bidirectional email synchronization between users and members
+    - Full-text search capabilities
+    - GDPR-compliant data management
+    
+    ## Domains:
+    - **Accounts**: User authentication and session management
+    - **Membership**: Club member data and custom properties
+  '''
+}
+
+// ============================================
+// ACCOUNTS DOMAIN
+// ============================================
+
+Table users {
+  id uuid [pk, not null, default: `gen_random_uuid()`, note: 'Primary identifier']
+  email citext [not null, unique, note: 'Email address (case-insensitive) - source of truth when linked to member']
+  hashed_password text [null, note: 'Bcrypt-hashed password (null for OIDC-only users)']
+  oidc_id text [null, unique, note: 'External OIDC identifier from authentication provider (e.g., Rauthy)']
+  member_id uuid [null, unique, note: 'Optional 1:1 link to member record']
+  
+  indexes {
+    email [unique, name: 'users_unique_email_index']
+    oidc_id [unique, name: 'users_unique_oidc_id_index']
+    member_id [unique, name: 'users_unique_member_index']
+  }
+  
+  Note: '''
+    **User Authentication Table**
+    
+    Handles user login accounts with two authentication strategies:
+    1. Password-based authentication (email + hashed_password)
+    2. OIDC/SSO authentication (email + oidc_id)
+    
+    **Relationship with Members:**
+    - Optional 1:1 relationship with members table (0..1 ↔ 0..1)
+    - A user can have 0 or 1 member (user.member_id can be NULL)
+    - A member can have 0 or 1 user (optional has_one relationship)
+    - Both entities can exist independently
+    - When linked, user.email is the source of truth
+    - Email changes sync bidirectionally between user ↔ member
+    
+    **Constraints:**
+    - At least one auth method required (password OR oidc_id)
+    - Email must be unique across all users
+    - OIDC ID must be unique if present
+    - Member can only be linked to one user (enforced by unique index)
+    
+    **Deletion Behavior:**
+    - When member is deleted → user.member_id set to NULL (user preserved)
+    - When user is deleted → member.user relationship cleared (member preserved)
+  '''
+}
+
+Table tokens {
+  jti text [pk, not null, note: 'JWT ID - unique token identifier']
+  subject text [not null, note: 'Token subject (usually user ID)']
+  purpose text [not null, note: 'Token purpose (e.g., "access", "refresh", "password_reset")']
+  expires_at timestamp [not null, note: 'Token expiration timestamp (UTC)']
+  extra_data jsonb [null, note: 'Additional token metadata']
+  created_at timestamp [not null, default: `now() AT TIME ZONE 'utc'`, note: 'Creation timestamp (UTC)']
+  updated_at timestamp [not null, default: `now() AT TIME ZONE 'utc'`, note: 'Last update timestamp (UTC)']
+  
+  indexes {
+    subject [name: 'tokens_subject_idx', note: 'For user token lookups']
+    expires_at [name: 'tokens_expires_at_idx', note: 'For token cleanup queries']
+    purpose [name: 'tokens_purpose_idx', note: 'For purpose-based queries']
+  }
+  
+  Note: '''
+    **AshAuthentication Token Management**
+    
+    Stores JWT tokens for authentication and authorization.
+    
+    **Token Purposes:**
+    - `access`: Short-lived access tokens for API requests
+    - `refresh`: Long-lived tokens for obtaining new access tokens
+    - `password_reset`: Temporary tokens for password reset flow
+    - `email_confirmation`: Temporary tokens for email verification
+    
+    **Token Lifecycle:**
+    - Tokens are created during login/registration
+    - Can be revoked by deleting the record
+    - Expired tokens should be cleaned up periodically
+    - `store_all_tokens? true` enables token tracking
+  '''
+}
+
+// ============================================
+// MEMBERSHIP DOMAIN
+// ============================================
+
+Table members {
+  id uuid [pk, not null, default: `uuid_generate_v7()`, note: 'UUIDv7 primary key (sortable by creation time)']
+  first_name text [not null, note: 'Member first name (min length: 1)']
+  last_name text [not null, note: 'Member last name (min length: 1)']
+  email text [not null, unique, note: 'Member email address (5-254 chars, validated)']
+  birth_date date [null, note: 'Date of birth (cannot be in future)']
+  paid boolean [null, note: 'Payment status flag']
+  phone_number text [null, note: 'Contact phone number (format: +?[0-9\- ]{6,20})']
+  join_date date [null, note: 'Date when member joined club (cannot be in future)']
+  exit_date date [null, note: 'Date when member left club (must be after join_date)']
+  notes text [null, note: 'Additional notes about member']
+  city text [null, note: 'City of residence']
+  street text [null, note: 'Street name']
+  house_number text [null, note: 'House number']
+  postal_code text [null, note: '5-digit German postal code']
+  search_vector tsvector [null, note: 'Full-text search index (auto-generated)']
+  
+  indexes {
+    email [unique, name: 'members_unique_email_index']
+    search_vector [type: gin, name: 'members_search_vector_idx', note: 'GIN index for full-text search']
+    email [name: 'members_email_idx']
+    last_name [name: 'members_last_name_idx', note: 'For name sorting']
+    join_date [name: 'members_join_date_idx', note: 'For date filters']
+    (paid) [name: 'members_paid_idx', type: btree, note: 'Partial index WHERE paid IS NOT NULL']
+  }
+  
+  Note: '''
+    **Club Member Master Data**
+    
+    Core entity for membership management containing:
+    - Personal information (name, birth date, email)
+    - Contact details (phone, address)
+    - Membership status (join/exit dates, payment status)
+    - Additional notes
+    
+    **Email Synchronization:**
+    When a member is linked to a user:
+    - User.email is the source of truth (overwrites member.email on link)
+    - Subsequent changes to either email sync bidirectionally
+    - Validates that email is not already used by another unlinked user
+    
+    **Full-Text Search:**
+    - `search_vector` is auto-updated via trigger
+    - Weighted fields: first_name (A), last_name (A), email (B), notes (B)
+    - Supports flexible member search across multiple fields
+    
+    **Relationships:**
+    - Optional 1:1 with users (0..1 ↔ 0..1) - authentication account
+    - 1:N with properties (custom dynamic fields)
+    
+    **Validation Rules:**
+    - first_name, last_name: min 1 character
+    - email: 5-254 characters, valid email format
+    - birth_date: cannot be in future
+    - join_date: cannot be in future
+    - exit_date: must be after join_date (if both present)
+    - phone_number: matches pattern ^\+?[0-9\- ]{6,20}$
+    - postal_code: exactly 5 digits
+  '''
+}
+
+Table properties {
+  id uuid [pk, not null, default: `gen_random_uuid()`, note: 'Primary identifier']
+  value jsonb [null, note: 'Union type value storage (format: {type: "string", value: "example"})']
+  member_id uuid [not null, note: 'Link to member']
+  property_type_id uuid [not null, note: 'Link to property type definition']
+  
+  indexes {
+    (member_id, property_type_id) [unique, name: 'properties_unique_property_per_member_index', note: 'One property per type per member']
+    member_id [name: 'properties_member_id_idx']
+    property_type_id [name: 'properties_property_type_id_idx']
+  }
+  
+  Note: '''
+    **Dynamic Custom Member Properties**
+    
+    Provides flexible, extensible attributes for members beyond the fixed schema.
+    
+    **Value Storage:**
+    - Stored as JSONB map with type discrimination
+    - Format: `{type: "string|integer|boolean|date|email", value: <actual_value>}`
+    - Allows multiple data types in single column
+    
+    **Supported Types:**
+    - `string`: Text data
+    - `integer`: Numeric data
+    - `boolean`: True/False flags
+    - `date`: Date values
+    - `email`: Validated email addresses
+    
+    **Constraints:**
+    - Each member can have only ONE property per property_type
+    - Properties are deleted when member is deleted (CASCADE)
+    - Property type cannot be deleted if properties exist (RESTRICT)
+    
+    **Use Cases:**
+    - Custom membership numbers
+    - Additional contact methods
+    - Club-specific attributes
+    - Flexible data model without schema migrations
+  '''
+}
+
+Table property_types {
+  id uuid [pk, not null, default: `gen_random_uuid()`, note: 'Primary identifier']
+  name text [not null, unique, note: 'Property name/identifier (e.g., "membership_number")']
+  value_type text [not null, note: 'Data type: string | integer | boolean | date | email']
+  description text [null, note: 'Human-readable description']
+  immutable boolean [not null, default: false, note: 'If true, value cannot be changed after creation']
+  required boolean [not null, default: false, note: 'If true, all members must have this property']
+  
+  indexes {
+    name [unique, name: 'property_types_unique_name_index']
+  }
+  
+  Note: '''
+    **Property Type Definitions**
+    
+    Defines the schema and behavior for custom member properties.
+    
+    **Attributes:**
+    - `name`: Unique identifier for the property type
+    - `value_type`: Enforces data type consistency
+    - `description`: Documentation for users/admins
+    - `immutable`: Prevents changes after initial creation (e.g., membership numbers)
+    - `required`: Enforces that all members must have this property
+    
+    **Constraints:**
+    - `value_type` must be one of: string, integer, boolean, date, email
+    - `name` must be unique across all property types
+    - Cannot be deleted if properties reference it (ON DELETE RESTRICT)
+    
+    **Examples:**
+    - Membership Number (string, immutable, required)
+    - Emergency Contact (string, mutable, optional)
+    - Certified Trainer (boolean, mutable, optional)
+    - Certification Date (date, immutable, optional)
+  '''
+}
+
+// ============================================
+// RELATIONSHIPS
+// ============================================
+
+// Optional 1:1 User ↔ Member Link
+// - A user can have 0 or 1 linked member (optional)
+// - A member can have 0 or 1 linked user (optional)
+// - Both can exist independently
+// - ON DELETE SET NULL: User preserved when member deleted
+// - Email Synchronization: When linking occurs, user.email becomes source of truth
+Ref: users.member_id - members.id [delete: set null]
+
+// Member → Properties (1:N)
+// - One member can have multiple properties
+// - Each property belongs to exactly one member
+// - ON DELETE CASCADE: Properties deleted when member deleted
+// - UNIQUE constraint: One property per type per member
+Ref: properties.member_id > members.id [delete: cascade]
+
+// Property → PropertyType (N:1)
+// - Many properties can reference one property type
+// - Property type defines the schema/behavior
+// - ON DELETE RESTRICT: Cannot delete type if properties exist
+Ref: properties.property_type_id > property_types.id [delete: restrict]
+
+// ============================================
+// ENUMS
+// ============================================
+
+// Valid data types for property values
+// Determines how Property.value is interpreted
+Enum property_value_type {
+  string [note: 'Text data']
+  integer [note: 'Numeric data']
+  boolean [note: 'True/False flags']
+  date [note: 'Date values']
+  email [note: 'Validated email addresses']
+}
+
+// Token purposes for different authentication flows
+Enum token_purpose {
+  access [note: 'Short-lived access tokens']
+  refresh [note: 'Long-lived refresh tokens']
+  password_reset [note: 'Password reset tokens']
+  email_confirmation [note: 'Email verification tokens']
+}
+
+// ============================================
+// TABLE GROUPS
+// ============================================
+
+TableGroup accounts_domain {
+  users
+  tokens
+  
+  Note: '''
+    **Accounts Domain**
+    
+    Handles user authentication and session management using AshAuthentication.
+    Supports multiple authentication strategies (Password, OIDC).
+  '''
+}
+
+TableGroup membership_domain {
+  members
+  properties
+  property_types
+  
+  Note: '''
+    **Membership Domain**
+    
+    Core business logic for club membership management.
+    Supports flexible, extensible member data model.
+  '''
+}
+
--- a/docs/development-progress-log.md
+++ b/docs/development-progress-log.md
--- a/docs/feature-roadmap.md
+++ b/docs/feature-roadmap.md
@ -0,0 +1,743 @@
+# Feature Roadmap & Implementation Plan
+
+**Project:** Mila - Membership Management System  
+**Last Updated:** 2025-11-10  
+**Status:** Planning Phase
+
+---
+
+## Table of Contents
+
+1. [Phase 1: Feature Area Breakdown](#phase-1-feature-area-breakdown)
+2. [Phase 2: API Endpoint Definition](#phase-2-api-endpoint-definition)
+3. [Phase 3: Implementation Task Creation](#phase-3-implementation-task-creation)
+4. [Phase 4: Task Organization and Prioritization](#phase-4-task-organization-and-prioritization)
+
+---
+
+## Phase 1: Feature Area Breakdown
+
+### Feature Areas
+
+#### 1. **Authentication & Authorization** 🔐
+
+**Current State:**
+- ✅ OIDC authentication (Rauthy)
+- ✅ Password-based authentication
+- ✅ User sessions and tokens
+- ✅ Basic authentication flows
+
+**Open Issues:**
+- [#171](https://git.local-it.org/local-it/mitgliederverwaltung/issues/171) - Ensure correct handling of Password login vs OIDC login (M)
+- [#146](https://git.local-it.org/local-it/mitgliederverwaltung/issues/146) - Translate "or" in the login screen (Low)
+- [#144](https://git.local-it.org/local-it/mitgliederverwaltung/issues/144) - Add language switch dropdown to login screen (Low)
+
+**Missing Features:**
+- ❌ Role-based access control (RBAC)
+- ❌ Permission system
+- ❌ Password reset flow
+- ❌ Email verification
+- ❌ Two-factor authentication (future)
+
+**Related Issues:**
+- [#191](https://git.local-it.org/local-it/mitgliederverwaltung/issues/191) - Implement Roles in Ash (M)
+- [#190](https://git.local-it.org/local-it/mitgliederverwaltung/issues/190) - Implement Permissions in Ash (M)
+- [#151](https://git.local-it.org/local-it/mitgliederverwaltung/issues/151) - Define implementation plan for roles and permissions (M) [3/7 tasks done]
+
+---
+
+#### 2. **Member Management** 👥
+
+**Current State:**
+- ✅ Member CRUD operations
+- ✅ Member profile with personal data
+- ✅ Address management
+- ✅ Membership status tracking
+- ✅ Full-text search (PostgreSQL tsvector)
+- ✅ Sorting by basic fields
+- ✅ User-Member linking (optional 1:1)
+- ✅ Email synchronization between User and Member
+
+**Open Issues:**
+- [#169](https://git.local-it.org/local-it/mitgliederverwaltung/issues/169) - Allow combined creation of Users/Members (M, Low priority)
+- [#168](https://git.local-it.org/local-it/mitgliederverwaltung/issues/168) - Allow user-member association in edit/create views (M, High priority)
+- [#165](https://git.local-it.org/local-it/mitgliederverwaltung/issues/165) - Pagination for list of members (S, Low priority)
+- [#162](https://git.local-it.org/local-it/mitgliederverwaltung/issues/162) - Implement fuzzy and substring search (M, Medium priority)
+- [#160](https://git.local-it.org/local-it/mitgliederverwaltung/issues/160) - Implement clear icon in searchbar (S, Low priority)
+- [#154](https://git.local-it.org/local-it/mitgliederverwaltung/issues/154) - Concept advanced search (Low priority, needs refinement)
+
+**Missing Features:**
+- ❌ Fuzzy search
+- ❌ Advanced filters (date ranges, multiple criteria)
+- ❌ Pagination (currently all members loaded)
+- ❌ Bulk operations (bulk delete, bulk update)
+- ❌ Member import/export (CSV, Excel)
+- ❌ Member profile photos/avatars
+- ❌ Member history/audit log
+- ❌ Duplicate detection
+
+---
+
+#### 3. **Custom Fields (Property System)** 🔧
+
+**Current State:**
+- ✅ Property types (string, integer, boolean, date, email)
+- ✅ Property type management
+- ✅ Dynamic property assignment to members
+- ✅ Union type storage (JSONB)
+
+**Open Issues:**
+- [#194](https://git.local-it.org/local-it/mitgliederverwaltung/issues/194) - Custom Fields: Harden implementation (S) [0/3 tasks]
+- [#157](https://git.local-it.org/local-it/mitgliederverwaltung/issues/157) - Concept how custom fields are handled (M, High priority) [0/4 tasks]
+- [#161](https://git.local-it.org/local-it/mitgliederverwaltung/issues/161) - Don't show birthday field for default configurations (S, Low priority)
+- [#153](https://git.local-it.org/local-it/mitgliederverwaltung/issues/153) - Sorting functionalities for custom fields (M, Low priority)
+
+**Missing Features:**
+- ❌ Default field visibility configuration
+- ❌ Field groups/categories
+- ❌ Conditional fields (show field X if field Y = value)
+- ❌ Field validation rules (min/max, regex patterns)
+- ❌ Required custom fields
+- ❌ Multi-select fields
+- ❌ File upload fields
+- ❌ Sorting by custom fields
+- ❌ Searching by custom fields
+
+---
+
+#### 4. **User Management** 👤
+
+**Current State:**
+- ✅ User CRUD operations
+- ✅ User list view
+- ✅ User profile view
+- ✅ Admin password setting
+- ✅ User-Member relationship
+
+**Missing Features:**
+- ❌ User roles assignment UI
+- ❌ User permissions management
+- ❌ User activity log
+- ❌ User invitation system
+- ❌ User onboarding flow
+- ❌ Self-service profile editing
+- ❌ Password change flow
+
+---
+
+#### 5. **Navigation & UX** 🧭
+
+**Current State:**
+- ✅ Basic navigation structure
+- ✅ Navbar with profile button
+- ✅ Member list as landing page
+- ✅ Breadcrumbs (basic)
+
+**Open Issues:**
+- [#188](https://git.local-it.org/local-it/mitgliederverwaltung/issues/188) - Check if searching just on typing is accessible (S, Low priority)
+- [#174](https://git.local-it.org/local-it/mitgliederverwaltung/issues/174) - Accessibility - aria-sort in tables (S, Low priority)
+
+**Missing Features:**
+- ❌ Dashboard/Home page
+- ❌ Quick actions menu
+- ❌ Recent activity widget
+- ❌ Keyboard shortcuts
+- ❌ Mobile navigation
+- ❌ Context-sensitive help
+- ❌ Onboarding tooltips
+
+---
+
+#### 6. **Internationalization (i18n)** 🌍
+
+**Current State:**
+- ✅ Gettext integration
+- ✅ German translations
+- ✅ English translations
+- ✅ Translation files for auth, errors, default
+
+**Open Issues:**
+- [#146](https://git.local-it.org/local-it/mitgliederverwaltung/issues/146) - Translate "or" in the login screen (Low)
+- [#144](https://git.local-it.org/local-it/mitgliederverwaltung/issues/144) - Add language switch dropdown to login screen (Low)
+
+**Missing Features:**
+- ❌ Language switcher UI
+- ❌ User-specific language preferences
+- ❌ Date/time localization
+- ❌ Number formatting (currency, decimals)
+- ❌ Complete translation coverage
+- ❌ RTL support (future)
+
+---
+
+#### 7. **Payment & Fees Management** 💰
+
+**Current State:**
+- ✅ Basic "paid" boolean field on members
+- ⚠️ No payment tracking
+
+**Open Issues:**
+- [#156](https://git.local-it.org/local-it/mitgliederverwaltung/issues/156) - Set up & document testing environment for vereinfacht.digital (L, Low priority)
+
+**Missing Features:**
+- ❌ Membership fee configuration
+- ❌ Payment records/transactions
+- ❌ Payment history per member
+- ❌ Payment reminders
+- ❌ Payment status tracking (pending, paid, overdue)
+- ❌ Invoice generation
+- ❌ vereinfacht.digital API integration
+- ❌ SEPA direct debit support
+- ❌ Payment reports
+
+**Related Milestones:**
+- Import transactions via vereinfacht API
+
+---
+
+#### 8. **Admin Panel & Configuration** ⚙️
+
+**Current State:**
+- ✅ AshAdmin integration (basic)
+- ⚠️ No user-facing admin UI
+
+**Open Issues:**
+- [#186](https://git.local-it.org/local-it/mitgliederverwaltung/issues/186) - Create Architecture docs in Repo (S, Low priority)
+
+**Missing Features:**
+- ❌ Global settings management
+- ❌ Club/Organization profile
+- ❌ Email templates configuration
+- ❌ Property type management UI (user-facing)
+- ❌ Role and permission management UI
+- ❌ System health dashboard
+- ❌ Audit log viewer
+- ❌ Backup/restore functionality
+
+**Related Milestones:**
+- As Admin I can configure settings globally
+
+---
+
+#### 9. **Communication & Notifications** 📧
+
+**Current State:**
+- ✅ Swoosh mailer integration
+- ✅ Email confirmation (via AshAuthentication)
+- ✅ Password reset emails (via AshAuthentication)
+- ⚠️ No member communication features
+
+**Missing Features:**
+- ❌ Email broadcast to members
+- ❌ Email templates (customizable)
+- ❌ Email to member groups/filters
+
+---
+
+#### 10. **Reporting & Analytics** 📊
+
+**Current State:**
+- ❌ No reporting features
+
+**Missing Features:**
+- ❌ Member statistics dashboard
+- ❌ Membership growth charts
+- ❌ Payment reports
+- ❌ Custom report builder
+- ❌ Export to PDF/CSV/Excel
+- ❌ Scheduled reports
+- ❌ Data visualization
+
+---
+
+#### 11. **Data Import/Export** 📥📤
+
+**Current State:**
+- ✅ Seed data script
+- ⚠️ No user-facing import/export
+
+**Missing Features:**
+- ❌ CSV import for members
+- ❌ Excel import for members
+- ❌ Import validation and preview
+- ❌ Import error handling
+- ❌ Bulk data export
+- ❌ Backup export
+- ❌ Data migration tools
+
+---
+
+#### 12. **Testing & Quality Assurance** 🧪
+
+**Current State:**
+- ✅ ExUnit test suite
+- ✅ Unit tests for resources
+- ✅ Integration tests for email sync
+- ✅ LiveView tests
+- ✅ Component tests
+- ✅ CI/CD pipeline (Drone)
+
+**Missing Features:**
+- ❌ E2E tests (browser automation)
+- ❌ Performance testing
+- ❌ Load testing
+- ❌ Security penetration testing
+- ❌ Accessibility testing automation
+- ❌ Visual regression testing
+- ❌ Test coverage reporting
+
+---
+
+#### 13. **Infrastructure & DevOps** 🚀
+
+**Current State:**
+- ✅ Docker Compose for development
+- ✅ Production Dockerfile
+- ✅ Drone CI/CD pipeline
+- ✅ Renovate for dependency updates
+- ⚠️ No staging environment
+
+**Open Issues:**
+- [#186](https://git.local-it.org/local-it/mitgliederverwaltung/issues/186) - Create Architecture docs in Repo (S, Low priority)
+
+**Missing Features:**
+- ❌ Staging environment
+- ❌ Automated deployment
+- ❌ Database backup automation
+- ❌ Monitoring and alerting
+- ❌ Error tracking (Sentry, etc.)
+- ❌ Log aggregation
+- ❌ Health checks and uptime monitoring
+
+**Related Milestones:**
+- We have a staging environment
+- We implement security measures
+
+---
+
+#### 14. **Security & Compliance** 🔒
+
+**Current State:**
+- ✅ OIDC authentication
+- ✅ Password hashing (bcrypt)
+- ✅ CSRF protection
+- ✅ SQL injection prevention (Ecto)
+- ✅ Sobelow security scans
+- ✅ Dependency auditing
+
+**Missing Features:**
+- ❌ Role-based access control (see #1)
+- ❌ Audit logging
+- ❌ GDPR compliance features (data export, deletion)
+- ❌ Session management (timeout, concurrent sessions)
+- ❌ Rate limiting
+- ❌ IP whitelisting/blacklisting
+- ❌ Security headers configuration
+- ❌ Data retention policies
+
+**Related Milestones:**
+- We implement security measures
+
+---
+
+#### 15. **Accessibility & Usability** ♿
+
+**Current State:**
+- ✅ Semantic HTML
+- ✅ Basic ARIA labels
+- ⚠️ Needs comprehensive audit
+
+**Open Issues:**
+- [#188](https://git.local-it.org/local-it/mitgliederverwaltung/issues/188) - Check if searching just on typing is accessible (S, Low priority)
+- [#174](https://git.local-it.org/local-it/mitgliederverwaltung/issues/174) - Accessibility - aria-sort in tables (S, Low priority)
+
+**Missing Features:**
+- ❌ Comprehensive accessibility audit (WCAG 2.1 Level AA)
+- ❌ Keyboard navigation improvements
+- ❌ Screen reader optimization
+- ❌ High contrast mode
+- ❌ Font size adjustments
+- ❌ Focus management
+- ❌ Skip links
+- ❌ Error announcements
+
+---
+
+### Feature Area Summary
+
+| Feature Area | Current Status | Priority | Complexity |
+|--------------|----------------|----------|------------|
+| **Authentication & Authorization** | 40% complete | **High** | Medium |
+| **Member Management** | 70% complete | **High** | Low-Medium |
+| **Custom Fields** | 50% complete | **High** | Medium |
+| **User Management** | 60% complete | Medium | Low |
+| **Navigation & UX** | 50% complete | Medium | Low |
+| **Internationalization** | 70% complete | Low | Low |
+| **Payment & Fees** | 5% complete | **High** | High |
+| **Admin Panel** | 20% complete | Medium | Medium |
+| **Communication** | 30% complete | Medium | Medium |
+| **Reporting** | 0% complete | Medium | Medium-High |
+| **Import/Export** | 10% complete | Low | Medium |
+| **Testing & QA** | 60% complete | Medium | Low-Medium |
+| **Infrastructure** | 70% complete | Medium | Medium |
+| **Security** | 50% complete | **High** | Medium-High |
+| **Accessibility** | 40% complete | Medium | Medium |
+
+---
+
+### Open Milestones (From Issues)
+
+1. ✅ **Ich kann einen neuen Kontakt anlegen** (Closed)
+2. 🔄 **I can search through the list of members - fulltext** (Open) - Related: #162, #154
+3. 🔄 **I can sort the list of members for specific fields** (Open) - Related: #153
+4. 🔄 **We have a intuitive navigation structure** (Open)
+5. 🔄 **We have different roles and permissions** (Open) - Related: #191, #190, #151
+6. 🔄 **As Admin I can configure settings globally** (Open)
+7. 🔄 **Accounts & Logins** (Open) - Related: #171, #169, #168
+8. 🔄 **I can add custom fields** (Open) - Related: #194, #157, #161
+9. 🔄 **Import transactions via vereinfacht API** (Open) - Related: #156
+10. 🔄 **We have a staging environment** (Open)
+11. 🔄 **We implement security measures** (Open)
+
+---
+
+---
+
+## Phase 2: API Endpoint Definition
+
+### Endpoint Types
+
+Since this is a **Phoenix LiveView** application with **Ash Framework**, we have three types of endpoints:
+
+1. **LiveView Endpoints** - Mount points and event handlers
+2. **HTTP Controller Endpoints** - Traditional REST-style endpoints
+3. **Ash Resource Actions** - Backend data layer API
+
+### Authentication Requirements Legend
+
+- 🔓 **Public** - No authentication required
+- 🔐 **Authenticated** - Requires valid user session
+- 👤 **User Role** - Requires specific user role
+- 🛡️ **Admin Only** - Requires admin privileges
+
+---
+
+### 1. Authentication & Authorization Endpoints
+
+#### HTTP Controller Endpoints
+
+| Method | Route | Purpose | Auth | Request | Response |
+|--------|-------|---------|------|---------|----------|
+| `GET` | `/auth/user/password/sign_in` | Show password login form | 🔓 | - | HTML form |
+| `POST` | `/auth/user/password/sign_in` | Submit password login | 🔓 | `{email, password}` | Redirect + session cookie |
+| `GET` | `/auth/user/rauthy` | Initiate OIDC flow | 🔓 | - | Redirect to Rauthy |
+| `GET` | `/auth/user/rauthy/callback` | Handle OIDC callback | 🔓 | `{code, state}` | Redirect + session cookie |
+| `POST` | `/auth/user/sign_out` | Sign out user | 🔐 | - | Redirect to login |
+| `GET` | `/auth/user/password/reset` | Show password reset form | 🔓 | - | HTML form |
+| `POST` | `/auth/user/password/reset` | Request password reset | 🔓 | `{email}` | Success message + email sent |
+| `GET` | `/auth/user/password/reset/:token` | Show reset password form | 🔓 | - | HTML form |
+| `POST` | `/auth/user/password/reset/:token` | Submit new password | 🔓 | `{password, password_confirmation}` | Redirect to login |
+
+#### Ash Resource Actions
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `User` | `:sign_in_with_password` | Password authentication | 🔓 | `{email, password}` | `{:ok, user}` or `{:error, reason}` |
+| `User` | `:sign_in_with_rauthy` | OIDC authentication | 🔓 | `{oidc_id, email, user_info}` | `{:ok, user}` or `{:error, reason}` |
+| `User` | `:register_with_password` | Create user with password | 🔓 | `{email, password}` | `{:ok, user}` |
+| `User` | `:register_with_rauthy` | Create user via OIDC | 🔓 | `{oidc_id, email}` | `{:ok, user}` |
+| `User` | `:request_password_reset` | Generate reset token | 🔓 | `{email}` | `{:ok, token}` |
+| `User` | `:reset_password` | Reset password with token | 🔓 | `{token, password}` | `{:ok, user}` |
+| `Token` | `:revoke` | Revoke authentication token | 🔐 | `{jti}` | `{:ok, token}` |
+
+#### **NEW: Role & Permission Actions** (Issue #191, #190, #151)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Role` | `:create` | Create new role | 🛡️ | `{name, description, permissions}` | `{:ok, role}` |
+| `Role` | `:list` | List all roles | 🔐 | - | `[%Role{}]` |
+| `Role` | `:update` | Update role | 🛡️ | `{id, name, permissions}` | `{:ok, role}` |
+| `Role` | `:delete` | Delete role | 🛡️ | `{id}` | `{:ok, role}` |
+| `User` | `:assign_role` | Assign role to user | 🛡️ | `{user_id, role_id}` | `{:ok, user}` |
+| `User` | `:remove_role` | Remove role from user | 🛡️ | `{user_id, role_id}` | `{:ok, user}` |
+| `Permission` | `:list` | List all permissions | 🔐 | - | `[%Permission{}]` |
+| `Permission` | `:check` | Check user permission | 🔐 | `{user_id, resource, action}` | `{:ok, boolean}` |
+
+---
+
+### 2. Member Management Endpoints
+
+#### LiveView Endpoints
+
+| Mount | Purpose | Auth | Query Params | Events |
+|-------|---------|------|--------------|--------|
+| `/members` | Member list with search/sort | 🔐 | `?search=&sort_by=&sort_dir=` | `search`, `sort`, `delete`, `select` |
+| `/members/new` | Create new member form | 🔐 | - | `save`, `cancel`, `add_property` |
+| `/members/:id` | Member detail view | 🔐 | - | `edit`, `delete`, `link_user` |
+| `/members/:id/edit` | Edit member form | 🔐 | - | `save`, `cancel`, `add_property`, `remove_property` |
+
+#### LiveView Event Handlers
+
+| Event | Purpose | Params | Response |
+|-------|---------|--------|----------|
+| `search` | Trigger search | `%{"search" => query}` | Update member list |
+| `sort` | Sort member list | `%{"field" => field}` | Update sorted list |
+| `delete` | Delete member | `%{"id" => id}` | Redirect to list |
+| `save` | Create/update member | `%{"member" => attrs}` | Redirect or show errors |
+| `link_user` | Link user to member | `%{"user_id" => id}` | Update member view |
+| `unlink_user` | Unlink user from member | - | Update member view |
+| `add_property` | Add custom property | `%{"property_type_id" => id, "value" => val}` | Update form |
+| `remove_property` | Remove custom property | `%{"property_id" => id}` | Update form |
+
+#### Ash Resource Actions
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Member` | `:create_member` | Create member | 🔐 | `{first_name, last_name, email, ...}` | `{:ok, member}` |
+| `Member` | `:read` | List/search members | 🔐 | `{search, sort_by, limit, offset}` | `[%Member{}]` |
+| `Member` | `:update_member` | Update member | 🔐 | `{id, attrs}` | `{:ok, member}` |
+| `Member` | `:destroy` | Delete member | 🔐 | `{id}` | `{:ok, member}` |
+| `Member` | `:search_fulltext` | Full-text search | 🔐 | `{query}` | `[%Member{}]` |
+| `Member` | `:link_to_user` | Link member to user | 🔐 | `{member_id, user_id}` | `{:ok, member}` |
+| `Member` | `:unlink_from_user` | Unlink from user | 🔐 | `{member_id}` | `{:ok, member}` |
+
+#### **NEW: Enhanced Search & Filter Actions** (Issue #162, #154, #165)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Member` | `:fuzzy_search` | Fuzzy text search | 🔐 | `{query, threshold}` | `[%Member{}]` |
+| `Member` | `:advanced_search` | Multi-criteria search | 🔐 | `{filters: [{field, op, value}]}` | `[%Member{}]` |
+| `Member` | `:paginate` | Paginated member list | 🔐 | `{page, per_page, filters}` | `{members, total, page_info}` |
+| `Member` | `:sort_by_custom_field` | Sort by property | 🔐 | `{property_type_id, direction}` | `[%Member{}]` |
+| `Member` | `:bulk_delete` | Delete multiple members | 🛡️ | `{ids: [id1, id2, ...]}` | `{:ok, count}` |
+| `Member` | `:bulk_update` | Update multiple members | 🛡️ | `{ids, attrs}` | `{:ok, count}` |
+| `Member` | `:export` | Export to CSV/Excel | 🔐 | `{format, filters}` | File download |
+| `Member` | `:import` | Import from CSV | 🛡️ | `{file, mapping}` | `{:ok, imported_count, errors}` |
+
+---
+
+### 3. Custom Fields (Property System) Endpoints
+
+#### LiveView Endpoints
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/property-types` | List property types | 🛡️ | `new`, `edit`, `delete` |
+| `/property-types/new` | Create property type | 🛡️ | `save`, `cancel` |
+| `/property-types/:id/edit` | Edit property type | 🛡️ | `save`, `cancel`, `delete` |
+
+#### Ash Resource Actions
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `PropertyType` | `:create` | Create property type | 🛡️ | `{name, value_type, description, ...}` | `{:ok, property_type}` |
+| `PropertyType` | `:read` | List property types | 🔐 | - | `[%PropertyType{}]` |
+| `PropertyType` | `:update` | Update property type | 🛡️ | `{id, attrs}` | `{:ok, property_type}` |
+| `PropertyType` | `:destroy` | Delete property type | 🛡️ | `{id}` | `{:ok, property_type}` |
+| `Property` | `:create` | Add property to member | 🔐 | `{member_id, property_type_id, value}` | `{:ok, property}` |
+| `Property` | `:update` | Update property value | 🔐 | `{id, value}` | `{:ok, property}` |
+| `Property` | `:destroy` | Remove property | 🔐 | `{id}` | `{:ok, property}` |
+
+#### **NEW: Enhanced Custom Fields** (Issue #194, #157, #161, #153)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `PropertyType` | `:set_default_visibility` | Show/hide by default | 🛡️ | `{id, visible}` | `{:ok, property_type}` |
+| `PropertyType` | `:set_required` | Mark as required | 🛡️ | `{id, required}` | `{:ok, property_type}` |
+| `PropertyType` | `:add_validation` | Add validation rule | 🛡️ | `{id, rule_type, params}` | `{:ok, property_type}` |
+| `PropertyType` | `:create_group` | Create field group | 🛡️ | `{name, property_type_ids}` | `{:ok, group}` |
+| `Property` | `:validate_value` | Validate property value | 🔐 | `{property_type_id, value}` | `{:ok, valid}` or `{:error, reason}` |
+
+---
+
+### 4. User Management Endpoints
+
+#### LiveView Endpoints
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/users` | User list | 🛡️ | `new`, `edit`, `delete`, `assign_role` |
+| `/users/new` | Create user form | 🛡️ | `save`, `cancel` |
+| `/users/:id` | User detail view | 🔐 | `edit`, `delete`, `change_password` |
+| `/users/:id/edit` | Edit user form | 🔐 | `save`, `cancel`, `link_member` |
+| `/profile` | Current user profile | 🔐 | `edit`, `change_password` |
+
+#### Ash Resource Actions
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `User` | `:create_user` | Create user (admin) | 🛡️ | `{email, member_id?}` | `{:ok, user}` |
+| `User` | `:read` | List users | 🛡️ | - | `[%User{}]` |
+| `User` | `:update_user` | Update user | 🔐 | `{id, email, member_id?}` | `{:ok, user}` |
+| `User` | `:destroy` | Delete user | 🛡️ | `{id}` | `{:ok, user}` |
+| `User` | `:admin_set_password` | Set password (admin) | 🛡️ | `{id, password}` | `{:ok, user}` |
+| `User` | `:change_password` | Change own password | 🔐 | `{current_password, new_password}` | `{:ok, user}` |
+
+#### **NEW: Combined User/Member Management** (Issue #169, #168)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `User` | `:create_with_member` | Create user + member together | 🛡️ | `{user: {...}, member: {...}}` | `{:ok, %{user, member}}` |
+| `User` | `:invite_user` | Send invitation email | 🛡️ | `{email, role_id, member_id?}` | `{:ok, invitation}` |
+| `User` | `:accept_invitation` | Accept invitation | 🔓 | `{token, password}` | `{:ok, user}` |
+
+---
+
+### 5. Navigation & UX Endpoints
+
+#### LiveView Endpoints
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/` | Dashboard/Home | 🔐 | - |
+| `/dashboard` | Dashboard view | 🔐 | Contextual based on role |
+
+#### HTTP Controller Endpoints
+
+| Method | Route | Purpose | Auth | Request | Response |
+|--------|-------|---------|------|---------|----------|
+| `GET` | `/health` | Health check | 🔓 | - | `{"status": "ok"}` |
+| `GET` | `/` | Root redirect | - | - | Redirect to dashboard or login |
+
+---
+
+### 6. Internationalization Endpoints
+
+#### HTTP Controller Endpoints
+
+| Method | Route | Purpose | Auth | Request | Response |
+|--------|-------|---------|------|---------|----------|
+| `POST` | `/locale` | Set user locale | 🔐 | `{locale: "de"}` | Redirect with cookie |
+| `GET` | `/locales` | List available locales | 🔓 | - | `["de", "en"]` |
+
+---
+
+### 7. Payment & Fees Management Endpoints
+
+#### LiveView Endpoints (NEW - Issue #156)
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/payments` | Payment list | 🔐 | `new`, `record_payment`, `send_reminder` |
+| `/payments/:id` | Payment detail | 🔐 | `edit`, `delete`, `mark_paid` |
+| `/fees` | Fee configuration | 🛡️ | `create`, `edit`, `delete` |
+| `/invoices` | Invoice list | 🔐 | `generate`, `download`, `send` |
+
+#### Ash Resource Actions (NEW)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Fee` | `:create` | Create fee type | 🛡️ | `{name, amount, frequency}` | `{:ok, fee}` |
+| `Fee` | `:read` | List fees | 🔐 | - | `[%Fee{}]` |
+| `Payment` | `:create` | Record payment | 🔐 | `{member_id, fee_id, amount, date}` | `{:ok, payment}` |
+| `Payment` | `:list_by_member` | Member payment history | 🔐 | `{member_id}` | `[%Payment{}]` |
+| `Payment` | `:mark_paid` | Mark as paid | 🔐 | `{id}` | `{:ok, payment}` |
+| `Invoice` | `:generate` | Generate invoice | 🔐 | `{member_id, fee_id, period}` | `{:ok, invoice}` |
+| `Invoice` | `:send` | Send invoice via email | 🔐 | `{id}` | `{:ok, sent}` |
+| `Payment` | `:import_vereinfacht` | Import from vereinfacht.digital | 🛡️ | `{transactions}` | `{:ok, count}` |
+
+---
+
+### 8. Admin Panel & Configuration Endpoints
+
+#### LiveView Endpoints (NEW)
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/admin` | Admin dashboard | 🛡️ | - |
+| `/admin/settings` | Global settings | 🛡️ | `save` |
+| `/admin/organization` | Organization profile | 🛡️ | `save` |
+| `/admin/email-templates` | Email template editor | 🛡️ | `create`, `edit`, `preview` |
+| `/admin/audit-log` | System audit log | 🛡️ | `filter`, `export` |
+
+#### Ash Resource Actions (NEW)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Setting` | `:get` | Get setting value | 🔐 | `{key}` | `value` |
+| `Setting` | `:set` | Set setting value | 🛡️ | `{key, value}` | `{:ok, setting}` |
+| `Setting` | `:list` | List all settings | 🛡️ | - | `[%Setting{}]` |
+| `Organization` | `:read` | Get organization info | 🔐 | - | `%Organization{}` |
+| `Organization` | `:update` | Update organization | 🛡️ | `{name, logo, ...}` | `{:ok, org}` |
+| `AuditLog` | `:list` | List audit entries | 🛡️ | `{filters, pagination}` | `[%AuditLog{}]` |
+
+---
+
+### 9. Communication & Notifications Endpoints
+
+#### LiveView Endpoints (NEW)
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/communications` | Communication history | 🔐 | `new`, `view` |
+| `/communications/new` | Create email broadcast | 🔐 | `select_recipients`, `preview`, `send` |
+| `/notifications` | User notifications | 🔐 | `mark_read`, `mark_all_read` |
+
+#### Ash Resource Actions (NEW)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `EmailBroadcast` | `:create` | Create broadcast | 🔐 | `{subject, body, recipient_filter}` | `{:ok, broadcast}` |
+| `EmailBroadcast` | `:send` | Send broadcast | 🔐 | `{id}` | `{:ok, sent_count}` |
+| `EmailTemplate` | `:create` | Create template | 🛡️ | `{name, subject, body}` | `{:ok, template}` |
+| `EmailTemplate` | `:render` | Render template | 🔐 | `{id, variables}` | `rendered_html` |
+| `Notification` | `:create` | Create notification | System | `{user_id, type, message}` | `{:ok, notification}` |
+| `Notification` | `:list_for_user` | Get user notifications | 🔐 | `{user_id}` | `[%Notification{}]` |
+| `Notification` | `:mark_read` | Mark as read | 🔐 | `{id}` | `{:ok, notification}` |
+
+---
+
+### 10. Reporting & Analytics Endpoints
+
+#### LiveView Endpoints (NEW)
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/reports` | Reports dashboard | 🔐 | `generate`, `schedule` |
+| `/reports/members` | Member statistics | 🔐 | `filter`, `export` |
+| `/reports/payments` | Payment reports | 🔐 | `filter`, `export` |
+| `/reports/custom` | Custom report builder | 🛡️ | `build`, `save`, `run` |
+
+#### Ash Resource Actions (NEW)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Report` | `:generate_member_stats` | Member statistics | 🔐 | `{date_range, filters}` | Statistics object |
+| `Report` | `:generate_payment_stats` | Payment statistics | 🔐 | `{date_range}` | Statistics object |
+| `Report` | `:export_to_csv` | Export report to CSV | 🔐 | `{report_type, filters}` | CSV file |
+| `Report` | `:export_to_pdf` | Export report to PDF | 🔐 | `{report_type, filters}` | PDF file |
+| `Report` | `:schedule` | Schedule recurring report | 🛡️ | `{report_type, frequency, recipients}` | `{:ok, schedule}` |
+
+---
+
+### 11. Data Import/Export Endpoints
+
+#### LiveView Endpoints (NEW)
+
+| Mount | Purpose | Auth | Events |
+|-------|---------|------|--------|
+| `/import` | Data import wizard | 🛡️ | `upload`, `map_fields`, `preview`, `import` |
+| `/export` | Data export tool | 🔐 | `select_data`, `configure`, `export` |
+
+#### Ash Resource Actions (NEW)
+
+| Resource | Action | Purpose | Auth | Input | Output |
+|----------|--------|---------|------|-------|--------|
+| `Member` | `:import_csv` | Import members from CSV | 🛡️ | `{file, field_mapping}` | `{:ok, imported, errors}` |
+| `Member` | `:validate_import` | Validate import data | 🛡️ | `{file, field_mapping}` | `{:ok, validation_results}` |
+| `Member` | `:export_csv` | Export members to CSV | 🔐 | `{filters}` | CSV file |
+| `Member` | `:export_excel` | Export members to Excel | 🔐 | `{filters}` | Excel file |
+| `Database` | `:export_backup` | Full database backup | 🛡️ | - | Backup file |
+| `Database` | `:import_backup` | Restore from backup | 🛡️ | `{file}` | `{:ok, restored}` |
+
+---
+
+
+---
+
+**References:**
+- Open Issues: https://git.local-it.org/local-it/mitgliederverwaltung/issues
+- Project Board: Sprint 8 (23.10 - 13.11)
+- Architecture: See [`CODE_GUIDELINES.md`](../CODE_GUIDELINES.md)
+- Database Schema: See [`database-schema-readme.md`](database-schema-readme.md)
+
--- a/lib/membership/email.ex
+++ b/lib/membership/email.ex
@ -1,4 +1,37 @@
 defmodule Mv.Membership.Email do
+  @moduledoc """
+  Custom Ash type for validated email addresses.
+
+  ## Overview
+  This type extends `:string` with email-specific validation constraints.
+  It ensures that email values stored in Property resources are valid email
+  addresses according to a standard regex pattern.
+
+  ## Validation Rules
+  - Minimum length: 5 characters
+  - Maximum length: 254 characters (RFC 5321 maximum)
+  - Pattern: Standard email format (username@domain.tld)
+  - Automatic trimming of leading/trailing whitespace
+
+  ## Usage
+  This type is used in the Property union type for properties with
+  `value_type: :email` in PropertyType definitions.
+
+  ## Example
+      # In a property type definition
+      PropertyType.create!(%{
+        name: "work_email",
+        value_type: :email
+      })
+
+      # Valid values
+      "user@example.com"
+      "first.last@company.co.uk"
+
+      # Invalid values
+      "not-an-email"      # Missing @ and domain
+      "a@b"               # Too short
+  """
  @match_pattern ~S/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/
  @match_regex Regex.compile!(@match_pattern)
  @min_length 5
--- a/lib/membership/member.ex
+++ b/lib/membership/member.ex
@ -1,4 +1,36 @@
 defmodule Mv.Membership.Member do
+  @moduledoc """
+  Ash resource representing a club member.
+
+  ## Overview
+  Members are the core entity in the membership management system. Each member
+  can have:
+  - Personal information (name, email, phone, address)
+  - Optional link to a User account (1:1 relationship)
+  - Dynamic custom properties via PropertyType system
+  - Full-text searchable profile
+
+  ## Email Synchronization
+  When a member is linked to a user account, emails are automatically synchronized
+  bidirectionally. User.email is the source of truth on initial link.
+  See `Mv.EmailSync` for details.
+
+  ## Relationships
+  - `has_many :properties` - Dynamic custom fields
+  - `has_one :user` - Optional authentication account link
+
+  ## Validations
+  - Required: first_name, last_name, email
+  - Email format validation (using EctoCommons.EmailValidator)
+  - Phone number format: international format with 6-20 digits
+  - Postal code format: exactly 5 digits (German format)
+  - Date validations: birth_date and join_date not in future, exit_date after join_date
+  - Email uniqueness: prevents conflicts with unlinked users
+
+  ## Full-Text Search
+  Members have a `search_vector` attribute (tsvector) that is automatically
+  updated via database trigger. Search includes name, email, notes, and contact fields.
+  """
  use Ash.Resource,
    domain: Mv.Membership,
    data_layer: AshPostgres.DataLayer
--- a/lib/membership/membership.ex
+++ b/lib/membership/membership.ex
@ -1,4 +1,21 @@
 defmodule Mv.Membership do
+  @moduledoc """
+  Ash Domain for membership management.
+
+  ## Resources
+  - `Member` - Club members with personal information and custom properties
+  - `Property` - Dynamic custom field values attached to members
+  - `PropertyType` - Schema definitions for custom properties
+
+  ## Public API
+  The domain exposes these main actions:
+  - Member CRUD: `create_member/1`, `list_members/0`, `update_member/2`, `destroy_member/1`
+  - Property management: `create_property/1`, `list_property/0`, etc.
+  - PropertyType management: `create_property_type/1`, `list_property_types/0`, etc.
+
+  ## Admin Interface
+  The domain is configured with AshAdmin for management UI.
+  """
  use Ash.Domain,
    extensions: [AshAdmin.Domain, AshPhoenix]

--- a/lib/membership/property.ex
+++ b/lib/membership/property.ex
@ -1,4 +1,36 @@
 defmodule Mv.Membership.Property do
+  @moduledoc """
+  Ash resource representing a custom property value for a member.
+
+  ## Overview
+  Properties implement the Entity-Attribute-Value (EAV) pattern, allowing
+  dynamic custom fields to be attached to members. Each property links a
+  member to a property type and stores the actual value.
+
+  ## Value Storage
+  Values are stored using Ash's union type with JSONB storage format:
+  ```json
+  {
+    "type": "string",
+    "value": "example"
+  }
+  ```
+
+  ## Supported Types
+  - `:string` - Text data
+  - `:integer` - Numeric data
+  - `:boolean` - True/false flags
+  - `:date` - Date values
+  - `:email` - Validated email addresses (custom type)
+
+  ## Relationships
+  - `belongs_to :member` - The member this property belongs to (CASCADE delete)
+  - `belongs_to :property_type` - The property type definition
+
+  ## Constraints
+  - Each member can have only one property per property type (unique composite index)
+  - Properties are deleted when the associated member is deleted (CASCADE)
+  """
  use Ash.Resource,
    domain: Mv.Membership,
    data_layer: AshPostgres.DataLayer
--- a/lib/membership/property_type.ex
+++ b/lib/membership/property_type.ex
@ -1,4 +1,48 @@
 defmodule Mv.Membership.PropertyType do
+  @moduledoc """
+  Ash resource defining the schema for custom member properties.
+
+  ## Overview
+  PropertyTypes define the "schema" for custom fields in the membership system.
+  Each PropertyType specifies the name, data type, and behavior of a custom field
+  that can be attached to members via Property resources.
+
+  ## Attributes
+  - `name` - Unique identifier for the property (e.g., "phone_mobile", "birthday")
+  - `value_type` - Data type constraint (`:string`, `:integer`, `:boolean`, `:date`, `:email`)
+  - `description` - Optional human-readable description
+  - `immutable` - If true, property values cannot be changed after creation
+  - `required` - If true, all members must have this property (future feature)
+
+  ## Supported Value Types
+  - `:string` - Text data (unlimited length)
+  - `:integer` - Numeric data (64-bit integers)
+  - `:boolean` - True/false flags
+  - `:date` - Date values (no time component)
+  - `:email` - Validated email addresses
+
+  ## Relationships
+  - `has_many :properties` - All property values of this type
+
+  ## Constraints
+  - Name must be unique across all property types
+  - Cannot delete a property type that has existing property values (RESTRICT)
+
+  ## Examples
+      # Create a new property type
+      PropertyType.create!(%{
+        name: "phone_mobile",
+        value_type: :string,
+        description: "Mobile phone number"
+      })
+
+      # Create a required property type
+      PropertyType.create!(%{
+        name: "emergency_contact",
+        value_type: :string,
+        required: true
+      })
+  """
  use Ash.Resource,
    domain: Mv.Membership,
    data_layer: AshPostgres.DataLayer
--- a/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex
+++ b/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex
@ -10,6 +10,20 @@ defmodule Mv.Accounts.User.Senders.SendNewUserConfirmationEmail do

  alias Mv.Mailer

+  @doc """
+  Sends a confirmation email to a new user.
+
+  This function is called automatically by AshAuthentication when a new
+  user registers and needs to confirm their email address.
+
+  ## Parameters
+  - `user` - The user record who needs to confirm their email
+  - `token` - The confirmation token to include in the email link
+  - `_opts` - Additional options (unused)
+
+  ## Returns
+  The Swoosh.Email delivery result from `Mailer.deliver!/1`.
+  """
  @impl true
  def send(user, token, _) do
    new()
--- a/lib/mv/accounts/user/senders/send_password_reset_email.ex
+++ b/lib/mv/accounts/user/senders/send_password_reset_email.ex
@ -10,6 +10,20 @@ defmodule Mv.Accounts.User.Senders.SendPasswordResetEmail do

  alias Mv.Mailer

+  @doc """
+  Sends a password reset email to a user.
+
+  This function is called automatically by AshAuthentication when a user
+  requests a password reset.
+
+  ## Parameters
+  - `user` - The user record requesting the password reset
+  - `token` - The password reset token to include in the email link
+  - `_opts` - Additional options (unused)
+
+  ## Returns
+  The Swoosh.Email delivery result from `Mailer.deliver!/1`.
+  """
  @impl true
  def send(user, token, _) do
    new()
--- a/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex
+++ b/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex
@ -9,6 +9,22 @@ defmodule Mv.Accounts.User.Validations.EmailNotUsedByOtherMember do
  """
  use Ash.Resource.Validation

+  @doc """
+  Validates email uniqueness across linked User-Member pairs.
+
+  This validation ensures that when a user is linked to a member, their email
+  does not conflict with another member's email. It only runs when necessary
+  to avoid blocking valid operations (see `@moduledoc` for trigger conditions).
+
+  ## Parameters
+  - `changeset` - The Ash changeset being validated
+  - `_opts` - Options passed to the validation (unused)
+  - `_context` - Ash context map (unused)
+
+  ## Returns
+  - `:ok` if validation passes or should be skipped
+  - `{:error, field: :email, message: ..., value: ...}` if validation fails
+  """
  @impl true
  def validate(changeset, _opts, _context) do
    email_changing? = Ash.Changeset.changing_attribute?(changeset, :email)
--- a/lib/mv/email_sync/changes/sync_member_email_to_user.ex
+++ b/lib/mv/email_sync/changes/sync_member_email_to_user.ex
@ -10,6 +10,21 @@ defmodule Mv.EmailSync.Changes.SyncMemberEmailToUser do
  use Ash.Resource.Change
  alias Mv.EmailSync.{Helpers, Loader}

+  @doc """
+  Implements the email synchronization from Member to User.
+
+  This function is called automatically by Ash when the configured trigger
+  conditions are met (see `@moduledoc` for trigger details).
+
+  ## Parameters
+  - `changeset` - The Ash changeset being processed
+  - `_opts` - Options passed to the change (unused)
+  - `context` - Ash context map containing metadata (e.g., `:syncing_email` flag)
+
+  ## Returns
+  Modified changeset with email synchronization applied, or original changeset
+  if recursion detected.
+  """
  @impl true
  def change(changeset, _opts, context) do
    # Only recursion protection needed - trigger logic is in `where` clauses
--- a/lib/mv/email_sync/changes/sync_user_email_to_member.ex
+++ b/lib/mv/email_sync/changes/sync_user_email_to_member.ex
@ -12,6 +12,21 @@ defmodule Mv.EmailSync.Changes.SyncUserEmailToMember do
  use Ash.Resource.Change
  alias Mv.EmailSync.{Helpers, Loader}

+  @doc """
+  Implements the email synchronization from User to Member.
+
+  This function is called automatically by Ash when the configured trigger
+  conditions are met (see `@moduledoc` for trigger details).
+
+  ## Parameters
+  - `changeset` - The Ash changeset being processed
+  - `_opts` - Options passed to the change (unused)
+  - `context` - Ash context map containing metadata (e.g., `:syncing_email` flag)
+
+  ## Returns
+  Modified changeset with email synchronization applied, or original changeset
+  if recursion detected.
+  """
  @impl true
  def change(changeset, _opts, context) do
    # Only recursion protection needed - trigger logic is in `where` clauses
--- a/lib/mv/membership/member/validations/email_not_used_by_other_user.ex
+++ b/lib/mv/membership/member/validations/email_not_used_by_other_user.ex
@ -9,6 +9,22 @@ defmodule Mv.Membership.Member.Validations.EmailNotUsedByOtherUser do
  """
  use Ash.Resource.Validation

+  @doc """
+  Validates email uniqueness across linked Member-User pairs.
+
+  This validation ensures that when a member is linked to a user, their email
+  does not conflict with another user's email. It only runs when necessary
+  to avoid blocking valid operations (see `@moduledoc` for trigger conditions).
+
+  ## Parameters
+  - `changeset` - The Ash changeset being validated
+  - `_opts` - Options passed to the validation (unused)
+  - `_context` - Ash context map (unused)
+
+  ## Returns
+  - `:ok` if validation passes or should be skipped
+  - `{:error, field: :email, message: ..., value: ...}` if validation fails
+  """
  @impl true
  def validate(changeset, _opts, _context) do
    email_changing? = Ash.Changeset.changing_attribute?(changeset, :email)
--- a/lib/mv/secrets.ex
+++ b/lib/mv/secrets.ex
@ -1,4 +1,23 @@
 defmodule Mv.Secrets do
+  @moduledoc """
+  Secret provider for AshAuthentication.
+
+  ## Purpose
+  Provides runtime configuration secrets for Ash Authentication strategies,
+  particularly for OIDC (Rauthy) authentication.
+
+  ## Configuration Source
+  Secrets are read from the `:rauthy` key in the application configuration,
+  which is typically set in `config/runtime.exs` from environment variables:
+  - `OIDC_CLIENT_ID`
+  - `OIDC_CLIENT_SECRET`
+  - `OIDC_BASE_URL`
+  - `OIDC_REDIRECT_URI`
+
+  ## Usage
+  This module is automatically called by AshAuthentication when resolving
+  secrets for the User resource's OIDC strategy.
+  """
  use AshAuthentication.Secret

  def secret_for(
--- a/lib/mv_web/auth_overrides.ex
+++ b/lib/mv_web/auth_overrides.ex
@ -1,4 +1,16 @@
 defmodule MvWeb.AuthOverrides do
+  @moduledoc """
+  UI customizations for AshAuthentication Phoenix components.
+
+  ## Overrides
+  - `SignIn` - Restricts form width to prevent full-width display
+  - `Banner` - Replaces default logo with "Mitgliederverwaltung" text
+  - `HorizontalRule` - Translates "or" text to German
+
+  ## Documentation
+  For complete reference on available overrides, see:
+  https://hexdocs.pm/ash_authentication_phoenix/ui-overrides.html
+  """
  use AshAuthentication.Phoenix.Overrides
  use Gettext, backend: MvWeb.Gettext

--- a/lib/mv_web/live/member_live/form.ex
+++ b/lib/mv_web/live/member_live/form.ex
@ -1,4 +1,33 @@
 defmodule MvWeb.MemberLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing members.
+
+  ## Features
+  - Create new members with personal information
+  - Edit existing member details
+  - Manage custom properties (dynamic fields)
+  - Real-time validation with visual feedback
+  - Link/unlink user accounts
+
+  ## Form Fields
+  **Required:**
+  - first_name, last_name, email
+
+  **Optional:**
+  - birth_date, phone_number, address fields (city, street, house_number, postal_code)
+  - join_date, exit_date
+  - paid status
+  - notes
+
+  ## Custom Properties
+  Members can have dynamic custom properties defined by PropertyTypes.
+  The form dynamically renders inputs based on available PropertyTypes.
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update member)
+  - Property management events for adding/removing custom fields
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/member_live/index.ex
+++ b/lib/mv_web/live/member_live/index.ex
@ -1,8 +1,39 @@
 defmodule MvWeb.MemberLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing the member list.
+
+  ## Features
+  - Full-text search across member profiles using PostgreSQL tsvector
+  - Sortable columns (name, email, address fields)
+  - Bulk selection for future batch operations
+  - Real-time updates via LiveView
+  - Bookmarkable URLs with query parameters
+
+  ## URL Parameters
+  - `query` - Search query string for full-text search
+  - `sort_field` - Field to sort by (e.g., :first_name, :email, :join_date)
+  - `sort_order` - Sort direction (:asc or :desc)
+
+  ## Events
+  - `delete` - Remove a member from the database
+  - `select_member` - Toggle individual member selection
+  - `select_all` - Toggle selection of all visible members
+
+  ## Implementation Notes
+  - Search uses PostgreSQL full-text search (plainto_tsquery)
+  - Sort state is synced with URL for bookmarkability
+  - Components communicate via `handle_info` for decoupling
+  """
  use MvWeb, :live_view
  import Ash.Expr
  import Ash.Query

+  @doc """
+  Initializes the LiveView state.
+
+  Sets up initial assigns for page title, search query, sort configuration,
+  and member selection. Actual data loading happens in `handle_params/3`.
+  """
  @impl true
  def mount(_params, _session, socket) do
    socket =
@ -21,7 +52,14 @@ defmodule MvWeb.MemberLive.Index do
  # Handle Events
  # -----------------------------------------------------------------

-  # Delete a member
+  @doc """
+  Handles member-related UI events.
+
+  ## Supported events:
+  - `"delete"` - Removes a member from the database
+  - `"select_member"` - Toggles individual member selection
+  - `"select_all"` - Toggles selection of all visible members
+  """
  @impl true
  def handle_event("delete", %{"id" => id}, socket) do
    member = Ash.get!(Mv.Membership.Member, id)
@ -31,7 +69,6 @@ defmodule MvWeb.MemberLive.Index do
    {:noreply, assign(socket, :members, updated_members)}
  end

-  # Selects one member in the list of members
  @impl true
  def handle_event("select_member", %{"id" => id}, socket) do
    selected =
@ -44,7 +81,6 @@ defmodule MvWeb.MemberLive.Index do
    {:noreply, assign(socket, :selected_members, selected)}
  end

-  #  Selects all members in the list of members
  @impl true
  def handle_event("select_all", _params, socket) do
    members = socket.assigns.members
@ -65,57 +101,23 @@ defmodule MvWeb.MemberLive.Index do
  # Handle Infos from Child Components
  # -----------------------------------------------------------------

-  # Sorts the list of members according to a field, when you click on the column header
+  @doc """
+  Handles messages from child components.
+
+  ## Supported messages:
+  - `{:sort, field}` - Sort event from SortHeaderComponent. Updates sort field/order and syncs URL
+  - `{:search_changed, query}` - Search event from SearchBarComponent. Filters members and syncs URL
+  """
  @impl true
  def handle_info({:sort, field_str}, socket) do
    field = String.to_existing_atom(field_str)
-    old_field = socket.assigns.sort_field
+    {new_field, new_order} = determine_new_sort(field, socket)

-    {new_order, new_field} =
-      if socket.assigns.sort_field == field do
-        {toggle_order(socket.assigns.sort_order), field}
-      else
-        {:asc, field}
-      end
-
-    active_id = :"sort_#{new_field}"
-    old_id = :"sort_#{old_field}"
-
-    # Update the new SortHeader
-    send_update(MvWeb.Components.SortHeaderComponent,
-      id: active_id,
-      sort_field: new_field,
-      sort_order: new_order
-    )
-
-    # Reset the current SortHeader
-    send_update(MvWeb.Components.SortHeaderComponent,
-      id: old_id,
-      sort_field: new_field,
-      sort_order: new_order
-    )
-
-    existing_search_query = socket.assigns.query
-
-    # Build the URL with queries
-    query_params = %{
-      "query" => existing_search_query,
-      "sort_field" => Atom.to_string(new_field),
-      "sort_order" => Atom.to_string(new_order)
-    }
-
-    # Set the new path with params
-    new_path = ~p"/members?#{query_params}"
-
-    # Push the new URL
-    {:noreply,
-     push_patch(socket,
-       to: new_path,
-       replace: true
-     )}
+    socket
+    |> update_sort_components(socket.assigns.sort_field, new_field, new_order)
+    |> push_sort_url(new_field, new_order)
  end

-  # Function to handle search
  @impl true
  def handle_info({:search_changed, q}, socket) do
    socket = load_members(socket, q)
@ -144,6 +146,13 @@ defmodule MvWeb.MemberLive.Index do
  # -----------------------------------------------------------------
  # Handle Params from the URL
  # -----------------------------------------------------------------
+  @doc """
+  Handles URL parameter changes.
+
+  Parses query parameters for search query, sort field, and sort order,
+  then loads members accordingly. This enables bookmarkable URLs and
+  browser back/forward navigation.
+  """
  @impl true
  def handle_params(params, _url, socket) do
    socket =
@ -158,6 +167,55 @@ defmodule MvWeb.MemberLive.Index do
  # -------------------------------------------------------------
  # FUNCTIONS
  # -------------------------------------------------------------
+
+  # Determines new sort field and order based on current state
+  defp determine_new_sort(field, socket) do
+    if socket.assigns.sort_field == field do
+      {field, toggle_order(socket.assigns.sort_order)}
+    else
+      {field, :asc}
+    end
+  end
+
+  # Updates both the active and old SortHeader components
+  defp update_sort_components(socket, old_field, new_field, new_order) do
+    active_id = :"sort_#{new_field}"
+    old_id = :"sort_#{old_field}"
+
+    # Update the new SortHeader
+    send_update(MvWeb.Components.SortHeaderComponent,
+      id: active_id,
+      sort_field: new_field,
+      sort_order: new_order
+    )
+
+    # Reset the current SortHeader
+    send_update(MvWeb.Components.SortHeaderComponent,
+      id: old_id,
+      sort_field: new_field,
+      sort_order: new_order
+    )
+
+    socket
+  end
+
+  # Builds sort URL and pushes navigation patch
+  defp push_sort_url(socket, field, order) do
+    query_params = %{
+      "query" => socket.assigns.query,
+      "sort_field" => Atom.to_string(field),
+      "sort_order" => Atom.to_string(order)
+    }
+
+    new_path = ~p"/members?#{query_params}"
+
+    {:noreply,
+     push_patch(socket,
+       to: new_path,
+       replace: true
+     )}
+  end
+
  # Load members eg based on a query for sorting
  defp load_members(socket, search_query) do
    query =
--- a/lib/mv_web/live/member_live/show.ex
+++ b/lib/mv_web/live/member_live/show.ex
@ -1,4 +1,26 @@
 defmodule MvWeb.MemberLive.Show do
+  @moduledoc """
+  LiveView for displaying a single member's details.
+
+  ## Features
+  - Display all member information (personal, contact, address)
+  - Show linked user account (if exists)
+  - Display custom properties
+  - Navigate to edit form
+  - Return to member list
+
+  ## Displayed Information
+  - Basic: name, email, dates (birth, join, exit)
+  - Contact: phone number
+  - Address: street, house number, postal code, city
+  - Status: paid flag
+  - Relationships: linked user account
+  - Custom: dynamic properties from PropertyTypes
+
+  ## Navigation
+  - Back to member list
+  - Edit member (with return_to parameter for back navigation)
+  """
  use MvWeb, :live_view
  import Ash.Query

--- a/lib/mv_web/live/property_live/form.ex
+++ b/lib/mv_web/live/property_live/form.ex
@ -1,4 +1,35 @@
 defmodule MvWeb.PropertyLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing properties.
+
+  ## Features
+  - Create new properties with member and type selection
+  - Edit existing property values
+  - Value input adapts to property type (string, integer, boolean, date, email)
+  - Real-time validation
+
+  ## Form Fields
+  **Required:**
+  - member - Select which member owns this property
+  - property_type - Select the type (defines value type)
+  - value - The actual value (input type depends on property type)
+
+  ## Value Types
+  The form dynamically renders appropriate inputs based on property type:
+  - String: text input
+  - Integer: number input
+  - Boolean: checkbox
+  - Date: date picker
+  - Email: email input with validation
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update property)
+
+  ## Note
+  Properties are typically managed through the member edit form,
+  not through this standalone form.
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/property_live/index.ex
+++ b/lib/mv_web/live/property_live/index.ex
@ -1,4 +1,26 @@
 defmodule MvWeb.PropertyLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing properties.
+
+  ## Features
+  - List all properties with their values and types
+  - Show which member each property belongs to
+  - Display property type information
+  - Navigate to property details and edit forms
+  - Delete properties
+
+  ## Relationships
+  Each property is linked to:
+  - A member (the property owner)
+  - A property type (defining value type and behavior)
+
+  ## Events
+  - `delete` - Remove a property from the database
+
+  ## Note
+  Properties are typically managed through the member edit form.
+  This view provides a global overview of all properties.
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/property_live/show.ex
+++ b/lib/mv_web/live/property_live/show.ex
@ -1,4 +1,24 @@
 defmodule MvWeb.PropertyLive.Show do
+  @moduledoc """
+  LiveView for displaying a single property's details.
+
+  ## Features
+  - Display property value and type
+  - Show linked member
+  - Show property type definition
+  - Navigate to edit form
+  - Return to property list
+
+  ## Displayed Information
+  - Property value (formatted based on type)
+  - Property type name and description
+  - Member information (who owns this property)
+  - Property metadata (ID, timestamps if added)
+
+  ## Navigation
+  - Back to property list
+  - Edit property
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/property_type_live/form.ex
+++ b/lib/mv_web/live/property_type_live/form.ex
@ -1,4 +1,38 @@
 defmodule MvWeb.PropertyTypeLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing property types (admin).
+
+  ## Features
+  - Create new property type definitions
+  - Edit existing property types
+  - Select value type from supported types
+  - Set immutable and required flags
+  - Real-time validation
+
+  ## Form Fields
+  **Required:**
+  - name - Unique identifier (e.g., "phone_mobile", "emergency_contact")
+  - value_type - Data type (:string, :integer, :boolean, :date, :email)
+
+  **Optional:**
+  - description - Human-readable explanation
+  - immutable - If true, values cannot be changed after creation (default: false)
+  - required - If true, all members must have this property (default: false)
+
+  ## Value Type Selection
+  - `:string` - Text data (unlimited length)
+  - `:integer` - Numeric data
+  - `:boolean` - True/false flags
+  - `:date` - Date values
+  - `:email` - Validated email addresses
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update property type)
+
+  ## Security
+  Property type management is restricted to admin users.
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/property_type_live/index.ex
+++ b/lib/mv_web/live/property_type_live/index.ex
@ -1,4 +1,28 @@
 defmodule MvWeb.PropertyTypeLive.Index do
+  @moduledoc """
+  LiveView for managing property type definitions (admin).
+
+  ## Features
+  - List all property types
+  - Display type information (name, value type, description)
+  - Show immutable and required flags
+  - Create new property types
+  - Edit existing property types
+  - Delete property types (if no properties use them)
+
+  ## Displayed Information
+  - Name: Unique identifier for the property type
+  - Value type: Data type constraint (string, integer, boolean, date, email)
+  - Description: Human-readable explanation
+  - Immutable: Whether property values can be changed after creation
+  - Required: Whether all members must have this property (future feature)
+
+  ## Events
+  - `delete` - Remove a property type (only if no properties exist)
+
+  ## Security
+  Property type management is restricted to admin users.
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/property_type_live/show.ex
+++ b/lib/mv_web/live/property_type_live/show.ex
@ -1,4 +1,27 @@
 defmodule MvWeb.PropertyTypeLive.Show do
+  @moduledoc """
+  LiveView for displaying a single property type's details (admin).
+
+  ## Features
+  - Display property type definition
+  - Show all attributes (name, value type, description, flags)
+  - Navigate to edit form
+  - Return to property type list
+
+  ## Displayed Information
+  - Name: Unique identifier
+  - Value type: Data type constraint
+  - Description: Optional explanation
+  - Immutable flag: Whether values can be changed
+  - Required flag: Whether all members need this property
+
+  ## Navigation
+  - Back to property type list
+  - Edit property type
+
+  ## Security
+  Property type details are restricted to admin users.
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/user_live/form.ex
+++ b/lib/mv_web/live/user_live/form.ex
@ -1,4 +1,36 @@
 defmodule MvWeb.UserLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing users.
+
+  ## Features
+  - Create new users with email
+  - Edit existing user details
+  - Optional password setting (checkbox to toggle)
+  - Link/unlink member accounts
+  - Email synchronization with linked members
+
+  ## Form Fields
+  **Required:**
+  - email
+
+  **Optional:**
+  - password (for password authentication strategy)
+  - linked member (select from existing members)
+
+  ## Password Management
+  - New users: Can optionally set password with confirmation
+  - Existing users: Can change password (no confirmation required, admin action)
+  - Checkbox toggles password section visibility
+
+  ## Member Linking
+  Users can be linked to existing member accounts. When linked, emails are
+  synchronized bidirectionally with User.email as the source of truth.
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update user)
+  - `toggle_password_section` - Show/hide password fields
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live/user_live/index.ex
+++ b/lib/mv_web/live/user_live/index.ex
@ -1,4 +1,25 @@
 defmodule MvWeb.UserLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing the user list.
+
+  ## Features
+  - List all users with email and linked member
+  - Sort users by email (default)
+  - Delete users
+  - Navigate to user details and edit forms
+  - Bulk selection for future batch operations
+
+  ## Relationships
+  Displays linked member information when a user is connected to a member account.
+
+  ## Events
+  - `delete` - Remove a user from the database
+  - `select_user` - Toggle individual user selection
+  - `select_all` - Toggle selection of all visible users
+
+  ## Security
+  User deletion requires admin permissions (enforced by Ash policies).
+  """
  use MvWeb, :live_view
  import MvWeb.TableComponents

--- a/lib/mv_web/live/user_live/show.ex
+++ b/lib/mv_web/live/user_live/show.ex
@ -1,4 +1,29 @@
 defmodule MvWeb.UserLive.Show do
+  @moduledoc """
+  LiveView for displaying a single user's details.
+
+  ## Features
+  - Display user information (email, OIDC ID)
+  - Show authentication methods (password, OIDC)
+  - Display linked member account (if exists)
+  - Navigate to edit form
+  - Return to user list
+
+  ## Displayed Information
+  - Email address
+  - OIDC ID (if authenticated via OIDC)
+  - Password authentication status
+  - Linked member (name and email)
+
+  ## Authentication Status
+  Shows which authentication methods are enabled for the user:
+  - Password authentication (has hashed_password)
+  - OIDC authentication (has oidc_id)
+
+  ## Navigation
+  - Back to user list
+  - Edit user (with return_to parameter for back navigation)
+  """
  use MvWeb, :live_view

  @impl true
--- a/lib/mv_web/live_helpers.ex
+++ b/lib/mv_web/live_helpers.ex
@ -1,4 +1,16 @@
 defmodule MvWeb.LiveHelpers do
+  @moduledoc """
+  Shared LiveView lifecycle hooks and helper functions.
+
+  ## on_mount Hooks
+  - `:default` - Sets the user's locale from session (defaults to "de")
+
+  ## Usage
+  Add to LiveView modules via:
+  ```elixir
+  on_mount {MvWeb.LiveHelpers, :default}
+  ```
+  """
  def on_mount(:default, _params, session, socket) do
    locale = session["locale"] || "de"
    Gettext.put_locale(locale)
Author	SHA1	Message	Date
Moritz	8c8256c62f	docs: add @doc to public functions in EmailSync, Validations, and Senders All checks were successful continuous-integration/drone/push Build is passing Details Document public API functions with @doc for better tooling support: - EmailSync Changes: sync_user_email_to_member, sync_member_email_to_user - Validations: email_not_used_by_other_member, email_not_used_by_other_user - Senders: send_new_user_confirmation_email, send_password_reset_email	2025-11-10 17:03:54 +01:00
Moritz	5748fadf52	refactor: split long sort handler into smaller functions Extract determine_new_sort/2, update_sort_components/4, and push_sort_url/3 from handle_info({:sort, ...}). Reduces function from 46 to 7 lines.	2025-11-10 17:03:50 +01:00
Moritz	9c0f493840	docs: enable Credo ModuleDoc check and fix remaining modules Add @moduledoc to Secrets, LiveHelpers, AuthOverrides, and Membership domain. Enable Credo.Check.Readability.ModuleDoc in .credo.exs.	2025-11-10 17:03:43 +01:00
Moritz	1be55c96ff	docs: add @doc to public functions in MemberLive.Index Document LiveView callbacks (mount, handle_event, handle_info, handle_params) with comprehensive descriptions of their purpose and supported operations.	2025-11-10 17:03:38 +01:00
Moritz	ca84633641	docs: add @moduledoc to all LiveView modules Add comprehensive module documentation to 12 LiveView modules covering member, user, property, and property_type management views.	2025-11-10 17:03:32 +01:00
Moritz	409bc7bf2f	docs: add @moduledoc to core membership resources Add comprehensive module documentation to Member, Property, PropertyType, and Email. Improves code discoverability and enables ExDoc generation.	2025-11-10 17:03:19 +01:00
Moritz	20af015da6	docs: add feature roadmap All checks were successful continuous-integration/drone/push Build is passing Details	2025-11-10 15:56:59 +01:00
Moritz	27a6f5fd50	docs: add comprehensive project documentation and reduce redundancy All checks were successful continuous-integration/drone/push Build is passing Details Add CODE_GUIDELINES.md, database schema docs, and development-progress-log.md. Refactor README.md to eliminate redundant information by linking to detailed docs. Establish clear documentation hierarchy for better maintainability.	2025-11-10 14:28:30 +01:00