docs: add comprehensive project documentation and reduce redundancy

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.

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)
+

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.
+  '''
+}
+