feat(app): add support for user groups

.claude/commands/pre-push.md

@@ -0,0 +1,5 @@
+Before pushing to remote version control, ensure that the following is completed:
+
+1. run linters and formatters.
+2. run all tests using `mix test`.
+3. check any files that were created in the recent commits that part within the `docs/logs` folder and update any relevant content that is out of date with the code changes.

CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+## Project Overview
+
+SplitApp is a Phoenix Framework application built with Elixir. It uses Phoenix LiveView for interactive UI, SQLite for database storage, and includes user authentication functionality.
+
+## Tech Stack
+
+- **Backend**: Elixir with Phoenix Framework 1.7.20
+- **Database**: SQLite via Ecto
+- **Frontend**: Phoenix LiveView, TailwindCSS, and esbuild
+- **Authentication**: Built-in Phoenix authentication with bcrypt
+- **Email**: Swoosh for email delivery
+- **Server**: Bandit web server
+
+## Essential Commands
+
+### Development Setup
+
+```bash
+mix setup                # Install dependencies, create database, run migrations, and build assets
+mix deps.get            # Install Elixir dependencies
+mix ecto.setup          # Create database, run migrations, and seed data
+```
+
+### Running the Application
+
+```bash
+mix phx.server          # Start Phoenix server (visit http://localhost:4000)
+iex -S mix phx.server   # Start Phoenix server with interactive Elixir shell
+```
+
+### Database Management
+
+```bash
+mix ecto.create         # Create the database
+mix ecto.migrate        # Run pending migrations
+mix ecto.reset          # Drop, create, and migrate database
+mix ecto.gen.migration NAME  # Generate a new migration
+```
+
+### Testing
+
+```bash
+mix test                # Run all tests
+mix test FILE           # Run specific test file
+mix test FILE:LINE      # Run specific test at line number
+mix test --stale        # Run only stale tests
+```
+
+### Assets
+
+```bash
+mix assets.build        # Build CSS and JavaScript assets
+mix assets.deploy       # Build and minify assets for production
+```
+
+## Architecture
+
+### Directory Structure
+
+- **lib/split_app/**: Core business logic and contexts
+  - `accounts/`: User authentication domain (User, UserToken, UserNotifier)
+  - `application.ex`: OTP application supervision tree
+  - `repo.ex`: Ecto repository
+
+- **lib/split_app_web/**: Web layer
+  - `router.ex`: HTTP routes and pipelines
+  - `controllers/`: Traditional Phoenix controllers
+  - `live/`: LiveView modules for user authentication flows
+  - `components/`: Reusable UI components
+  - `user_auth.ex`: Authentication plugs and helpers
+
+- **priv/**: Private application files
+  - `repo/migrations/`: Database migrations
+  - `static/`: Static assets served directly
+
+### Key Architectural Patterns
+
+1. **Context Pattern**: Business logic is organized in contexts (e.g., Accounts). Each context manages its own domain and exposes a public API to the web layer.
+
+2. **LiveView Authentication**: User registration, login, password reset, and settings are implemented as LiveView modules with real-time validation.
+
+3. **Pipeline Architecture**: The router uses pipelines (`:browser`, `:api`, `:require_authenticated_user`) to apply common plugs to groups of routes.
+
+4. **Session Management**: User sessions are managed through database-backed tokens (UserToken) with configurable expiration times.
+
+### Authentication Flow
+
+The application includes complete user authentication with:
+
+- Registration with email confirmation
+- Login/logout with session tokens
+- Password reset via email
+- User settings management
+- Protected routes requiring authentication
+
+Routes are protected using custom plugs defined in `UserAuth`:
+
+- `redirect_if_user_is_authenticated`: Redirects logged-in users away from auth pages
+- `require_authenticated_user`: Ensures user is logged in
+- `fetch_current_user`: Loads current user into assigns
+
+### Database Schema
+
+The application uses SQLite with Ecto. Current tables:
+
+- `users`: User accounts with email and hashed passwords
+- `users_tokens`: Multi-purpose tokens for sessions, email confirmation, and password reset
+
+## Development Workflow
+
+1. Migrations are automatically run in development via `mix ecto.migrate`
+2. LiveView enables real-time UI updates without JavaScript
+3. TailwindCSS is configured for utility-first styling
+4. Hot code reloading is enabled in development for both Elixir and assets
+
+## Testing Approach
+
+Tests use ExUnit with:
+
+- `ConnCase`: For testing controllers and LiveViews with connection
+- `DataCase`: For testing contexts and schemas with database
+- Fixtures in `test/support/fixtures/` for test data
+- Ecto Sandbox for database isolation between tests
+
+# Purpose
+
+You are a software developer that is trying to create a new app that can help people track their expenses and properly split how much they spend. You want to create a web app using elixir and the Pheonix framework.
+
+# Development
+
+Use the following principles when making changes to this project:
+
+1. Prioritize pheonix framework code generators over coding from scratch. Utilize these tools to bootstrap the core domain models and structure of the app. You should not be creating too much custom code except within the concrete implementation of services that the generators have bootstrapped.
+
+2. When working on front end code, make sure that every new component or UI change conforms do the existing design language. Prioritize reusability instead of customizing every individual piece.

README.md

@@ -1,18 +1,72 @@
 # SplitApp
 
-To start your Phoenix server:
+SplitApp is a Phoenix Framework application for tracking expenses and splitting costs between users.
 
-  * Run `mix setup` to install and setup dependencies
-  * Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+## Getting Started
+
+### Development Setup
+
+```bash
+mix setup                # Install dependencies, create database, run migrations, and build assets
+mix deps.get            # Install Elixir dependencies
+mix ecto.setup          # Create database, run migrations, and seed data
+```
+
+### Running the Application
+
+```bash
+mix phx.server          # Start Phoenix server (visit http://localhost:4000)
+iex -S mix phx.server   # Start Phoenix server with interactive Elixir shell
+```
+
+### Database Management
+
+```bash
+mix ecto.create         # Create the database
+mix ecto.migrate        # Run pending migrations
+mix ecto.reset          # Drop, create, and migrate database
+mix ecto.gen.migration NAME  # Generate a new migration
+```
+
+### Testing
+
+```bash
+mix test                # Run all tests
+mix test FILE           # Run specific test file
+mix test FILE:LINE      # Run specific test at line number
+mix test --stale        # Run only stale tests
+```
+
+### Assets
+
+```bash
+mix assets.build        # Build CSS and JavaScript assets
+mix assets.deploy       # Build and minify assets for production
+```
+
+### Code Generation
+
+```bash
+mix phx.gen.live Context Schema table field:type  # Generate LiveView CRUD
+mix phx.gen.context Context Schema table field:type  # Generate context
+mix phx.gen.schema Context.Schema table field:type   # Generate schema
+```
+
+### Linting and Formatting
+
+```bash
+mix format              # Format Elixir code
+mix format --check-formatted  # Check if code is formatted
+```
 
 Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
 
 Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
 
 ## Learn more
 
-  * Official website: https://www.phoenixframework.org/
-  * Guides: https://hexdocs.pm/phoenix/overview.html
-  * Docs: https://hexdocs.pm/phoenix
-  * Forum: https://elixirforum.com/c/phoenix-forum
-  * Source: https://github.com/phoenixframework/phoenix
+- Official website: https://www.phoenixframework.org/
+- Guides: https://hexdocs.pm/phoenix/overview.html
+- Docs: https://hexdocs.pm/phoenix
+- Forum: https://elixirforum.com/c/phoenix-forum
+- Source: https://github.com/phoenixframework/phoenix

docs/logs/add-groups-feature.md

@@ -0,0 +1,160 @@
+---
+title: Adding Groups Feature to SplitApp
+date: 2025-08-24
+time: 17:28:00
+author: Claude
+tags: [groups, feature, authentication, liveview]
+---
+
+# Adding Groups Feature to SplitApp
+
+## Overview
+This document outlines the implementation of the Groups feature, which allows users to organize themselves into groups for expense tracking. Users can create groups, join groups, and view all groups they belong to on a dashboard landing page.
+
+## Database Changes
+
+### 1. Groups Table
+Created a new `groups` table with the following fields:
+- `id` - Primary key
+- `name` - String field for group name
+- `description` - Text field for group description
+- `inserted_at` - Timestamp
+- `updated_at` - Timestamp
+
+**Migration file:** `priv/repo/migrations/20250824171051_create_groups.exs`
+
+### 2. User-Groups Join Table
+Created a `user_groups` join table to establish many-to-many relationship:
+- `user_id` - Foreign key to users table
+- `group_id` - Foreign key to groups table
+- `inserted_at` - Timestamp
+- `updated_at` - Timestamp
+- Composite unique index on `[user_id, group_id]`
+- Individual indexes on `user_id` and `group_id`
+
+**Migration file:** `priv/repo/migrations/20250824171107_create_user_groups.exs`
+
+## Code Changes
+
+### 1. Context and Schemas
+
+#### Groups Context (`lib/split_app/groups.ex`)
+Generated using Phoenix context generator with additional functions:
+- `list_groups/0` - List all groups
+- `get_group!/1` - Get a single group
+- `create_group/1` - Create a new group
+- `update_group/2` - Update a group
+- `delete_group/1` - Delete a group
+- `list_user_groups/1` - List all groups for a specific user
+- `add_user_to_group/2` - Add a user to a group
+- `remove_user_from_group/2` - Remove a user from a group
+
+#### Group Schema (`lib/split_app/groups/group.ex`)
+- Basic fields: `name`, `description`
+- Association: `many_to_many :users` through `UserGroup`
+
+#### UserGroup Schema (`lib/split_app/groups/user_group.ex`)
+Join table schema with:
+- Belongs to both User and Group
+- Timestamps for tracking when users joined groups
+
+#### User Schema Updates (`lib/split_app/accounts/user.ex`)
+Added association: `many_to_many :groups` through `UserGroup`
+
+### 2. Web Layer
+
+#### Dashboard LiveView (`lib/split_app_web/live/dashboard_live.ex`)
+Custom landing page that:
+- Displays welcome message with user email
+- Shows all groups the user belongs to in card format
+- Provides empty state when user has no groups
+- Links to create new groups and browse all groups
+
+#### Group LiveViews (Generated)
+- `lib/split_app_web/live/group_live/index.ex` - List all groups
+- `lib/split_app_web/live/group_live/show.ex` - Show single group
+- `lib/split_app_web/live/group_live/form_component.ex` - Create/edit groups
+  - Modified to automatically add creator to new groups
+
+### 3. Router Updates (`lib/split_app_web/router.ex`)
+
+Added authenticated routes:
+```elixir
+live "/dashboard", DashboardLive, :index
+live "/groups", GroupLive.Index, :index
+live "/groups/new", GroupLive.Index, :new
+live "/groups/:id/edit", GroupLive.Index, :edit
+live "/groups/:id", GroupLive.Show, :show
+live "/groups/:id/show/edit", GroupLive.Show, :edit
+```
+
+### 4. Authentication Updates (`lib/split_app_web/user_auth.ex`)
+
+Changed `signed_in_path/1` to redirect authenticated users to `/dashboard` instead of home page.
+
+## UI/UX Features
+
+### Dashboard Page
+- **Welcome Header**: Personalized greeting with user email
+- **Group Cards**: Each group displayed as a card with:
+  - Group icon
+  - Group name
+  - Group description (or placeholder if none)
+  - Hover effects for better interactivity
+  - Click to navigate to group details
+- **Empty State**: When user has no groups:
+  - Informative icon and message
+  - Call-to-action button to create first group
+- **Actions**: 
+  - "Create New Group" button in header
+  - "Browse All Groups" link at bottom
+
+### Group Management
+- Create new groups with name and description
+- Creator automatically added as member
+- List view of all groups with edit/delete actions
+- Individual group pages (ready for future expense tracking features)
+
+## Test Data (`priv/repo/seeds.exs`)
+
+Created sample data for testing:
+
+**Users:**
+- user1@example.com (password: password12345)
+  - Member of: Weekend Trip, Monthly Groceries
+- user2@example.com (password: password12345)  
+  - Member of: Weekend Trip, Birthday Party
+
+**Groups:**
+- Weekend Trip - "Expenses for our weekend getaway"
+- Monthly Groceries - "Shared grocery expenses for the apartment"
+- Birthday Party - "Planning and expenses for Sarah's birthday"
+
+## Migration Commands
+
+```bash
+# Generate the Groups context
+mix phx.gen.context Groups Group groups name:string description:text
+
+# Generate LiveView pages (without context/schema)
+mix phx.gen.live Groups Group groups name:string description:text --no-context --no-schema
+
+# Generate user_groups migration
+mix ecto.gen.migration create_user_groups
+
+# Run migrations
+mix ecto.migrate
+
+# Reset database and run seeds
+mix ecto.reset
+```
+
+## Future Enhancements
+
+This foundation sets up the groups feature for future expense tracking functionality:
+- Add expenses to groups
+- Track who paid for what
+- Calculate splits and balances
+- Show group activity/history
+- Invite users to groups via email
+- Group member management and permissions