==================================================
 STORYGEN AI — STORY EXPORT
==================================================
Story ID:           31
Title:              Contact Management App (Training V.1)
Owner:              Salil Mhatre - Associate Director <salil@lithan.com>
App Type:           Conventional App
Input Type:         file
Status:             features_generated
Source File:        contact_management_app_v1.docx
Created:            2026-04-30 02:03:39 UTC
Updated:            2026-04-30 02:08:24 UTC
Features Generated: 2026-04-30 02:06:21 UTC
Total Clusters:     7
Total Features:     14

--- ORIGINAL INPUT ---
Contact Management App — User Story
Overview
This document describes a simple Contact Management Application with two core features: creating new contacts and managing contact lists with activities.
Features
Database Tables

--- USER STORY ---
# Contact Management Application

## Overview
This is a **Conventional App** that provides users with a centralized way to create, organize, and manage their personal or professional contacts. The application supports core CRUD operations on contacts and enables users to group contacts into lists and log activities (such as calls, meetings, or notes) against those contacts.

## Actors
- **End User**: Creates and maintains contact records, organizes contacts into lists, and logs activities related to interactions.
- **System Administrator**: Manages user accounts, monitors database health, and oversees data backups and access permissions.

## Goals
- Provide a simple, reliable way to create and store contact information.
- Enable users to organize contacts into lists for easier retrieval and segmentation.
- Allow users to track activities and interactions associated with each contact.
- Maintain data integrity and ensure quick access to contact records.

## User Story
As an **End User**, I want to **create contacts and organize them into lists with associated activities**, so that **I can keep track of my relationships and interactions in one centralized, easy-to-use application**.

## Detailed Workflow

### 1. Creating a New Contact
1. The user logs into the application and navigates to the **Contacts** section.
2. The user clicks the **"New Contact"** button, which opens a contact creation form.
3. The user fills in contact details:
   - First Name (required)
   - Last Name (required)
   - Email Address
   - Phone Number
   - Company / Organization
   - Job Title
   - Address
   - Notes
4. The user clicks **Save**.
5. The system validates the input (e.g., email format, required fields) and saves the contact to the **Contacts** table.
6. A confirmation message is displayed, and the new contact appears in the contact list view.

### 2. Managing Contact Lists
1. The user navigates to the **Lists** section.
2. The user can:
   - Create a new list (e.g., "Clients", "Vendors", "Friends") by clicking **"New List"** and providing a list name and optional description.
   - Edit or delete existing lists.
3. The user opens a list and adds contacts to it by selecting from existing contacts.
4. The system stores the relationship in the **ContactList_Members** join table.
5. The user can remove contacts from a list at any time.

### 3. Logging Activities Against Contacts
1. From a contact's detail page or a list view, the user clicks **"Log Activity"**.
2. The user selects the activity type (Call, Email, Meeting, Note, Task) and enters:
   - Date and time
   - Subject / Title
   - Description / Notes
   - Optional follow-up date
3. The user clicks **Save**, and the activity is recorded in the **Activities** table linked to the contact.
4. The activity appears in the contact's activity timeline, sorted chronologically.

### 4. Viewing and Searching
1. The user can search contacts by name, email, company, or list membership.
2. The user can filter contacts by list and view all activities associated with a contact.

## Database Tables (Proposed Schema)

- **Contacts**: `contact_id` (PK), `first_name`, `last_name`, `email`, `phone`, `company`, `job_title`, `address`, `notes`, `created_at`, `updated_at`, `owner_user_id` (FK)
- **ContactLists**: `list_id` (PK), `list_name`, `description`, `owner_user_id` (FK), `created_at`
- **ContactList_Members**: `list_id` (FK), `contact_id` (FK), `added_at` — composite PK
- **Activities**: `activity_id` (PK), `contact_id` (FK), `activity_type`, `subject`, `description`, `activity_date`, `follow_up_date`, `created_at`, `created_by_user_id` (FK)
- **Users**: `user_id` (PK), `username`, `email`, `password_hash`, `created_at`

## Acceptance Criteria

### Contact Creation
- The user can create a contact with at least a first name and last name.
- Email and phone fields are validated for proper format before saving.
- Duplicate detection warns the user if a contact with the same email already exists.
- The new contact is immediately visible in the contact list view after saving.

### Contact List Management
- The user can create, rename, and delete contact lists.
- The user can add a single contact to multiple lists.
- The user can add and remove contacts from a list without deleting the contact itself.
- Deleting a list does not delete the contacts within it; only the list and its memberships are removed.

### Activity Management
- The user can log an activity against any contact they own.
- Activities are displayed in reverse-chronological order on the contact's detail page.
- The user can edit or delete activities they have created.
- Activity type is required and must be selected from a predefined list.

### General
- All data is persisted in the database and survives application restarts.
- The user can only view and modify contacts, lists, and activities they own.
- The application provides clear success and error messages for all save/delete operations.
- All forms include validation and prevent submission of invalid data.

## Assumptions & Constraints
- Each user has their own private set of contacts; sharing or multi-user collaboration is out of scope for this version.
- Authentication is handled via standard username/password login.
- The application is web-based and accessed via a modern browser; mobile-specific UI is out of scope for this release.
- The activity types are predefined (Call, Email, Meeting, Note, Task) and not user-customizable in v1.
- No external integrations (e.g., email sync, calendar sync, CRM imports) are included in this initial release.
- The system supports a reasonable scale (e.g., up to ~10,000 contacts per user) without specialized performance tuning.

--- FEATURE LIST SUMMARY ---
This solution enables End Users to centralize personal and professional contacts, organize them into lists, and log every interaction in one place. The primary actors are the End User who manages contacts, lists, and activities, and the System Administrator who oversees user accounts and data integrity. The core flow runs from account setup to contact creation, list organization, activity logging, and finally search and review. The Master Data Configuration cluster holds user accounts, activity-type lookups, and ownership references shared across the app. Across 14 rows it delivers contact CRUD, list segmentation, and a chronological activity timeline.

Feature Clusters & Features:
• Master Data Configuration
  - 1. User Account Management — Maintains user identities, credentials, and ownership keys that secure every contact, list, and activity record.
  - 2. Activity Type Catalog — Reference list of allowed activity types (Call, Email, Meeting, Note, Task) used when logging interactions.
  - 3. Validation Rules Configuration — Centralized rules for email format, required fields, and duplicate detection applied across forms.
• Authentication & Access
  - 4. User Login and Session — Authenticates users by username and password and scopes their session to their own data only.
• Contact Intake
  - 5. Create New Contact — Captures a new contact's name, email, phone, company, and notes through a validated form.
  - 6. Duplicate Contact Detection — Warns the user before saving when an existing contact shares the same email address.
• Contact Maintenance
  - 7. Edit Contact Details — Lets the owner update any field on an existing contact and timestamps the change.
  - 8. Delete Contact — Removes a contact and its dependent activities and list memberships under owner control.
• List Organization
  - 9. Create and Manage Contact Lists — Allows users to create, rename, and delete named lists such as Clients or Vendors.
  - 10. Add and Remove List Members — Assigns existing contacts to one or more lists and removes them without deleting the contact.
• Activity Logging
  - 11. Log Activity Against Contact — Records an interaction with type, date, subject, description, and optional follow-up date.
  - 12. Edit or Delete Activity — Lets the creator amend or remove activities they previously logged on a contact.
• Search & Review
  - 13. Contact Search and Filter — Finds contacts by name, email, company, or list membership for quick retrieval.
  - 14. Contact Activity Timeline — Displays all activities for a contact in reverse-chronological order on the detail page.

--- FEATURE LIST (14 features across 7 clusters) ---

#1 | Cluster: Master Data Configuration | Feature: User Account Management
  Description: Maintains the master registry of application users and their credentials. Every contact, list, and activity is tied to a user_id from this table to enforce private ownership.
  Workflow:
    1. Administrator creates user records with username, email, and hashed password.
    2. System stores credentials securely in the Users table.
    3. User accounts are referenced as owner_user_id by contacts, lists, and activities.
    4. Administrator can deactivate or remove user accounts as needed.
  Table:       users
  Columns:     user_id (bigint, pk), username (varchar 100, unique), email (varchar 255), password_hash (varchar 255), created_at (timestamp), is_active (boolean)
  Actor:       System Administrator
  AI Agent:    None
  ----
#2 | Cluster: Master Data Configuration | Feature: Activity Type Catalog
  Description: Provides the fixed lookup of activity types used when users log interactions against contacts. Ensures consistency and reporting integrity across activity records.
  Workflow:
    1. Administrator seeds the catalog with predefined types: Call, Email, Meeting, Note, Task.
    2. System exposes the list to activity logging forms as a dropdown.
    3. Activity records reference activity_type_code as a foreign key.
    4. Catalog values are read-only for end users in v1.
  Table:       activity_types
  Columns:     activity_type_code (varchar 20, pk), display_name (varchar 50), description (varchar 255), is_active (boolean), sort_order (int)
  Actor:       System Administrator
  AI Agent:    None
  ----
#3 | Cluster: Master Data Configuration | Feature: Validation Rules Configuration
  Description: Centralizes form-validation rules such as required fields, email format, and duplicate-email detection. Reused by every create and edit form to enforce data integrity.
  Workflow:
    1. Administrator defines required fields and format rules per entity (contacts, activities, lists).
    2. Application loads rules at form-render time.
    3. Client and server validators apply the rule set on submit.
    4. Rules can be updated centrally without code changes.
  Table:       validation_rules
  Columns:     rule_id (bigint, pk), entity_name (varchar 50), field_name (varchar 50), rule_type (varchar 30), rule_value (varchar 255), error_message (varchar 255)
  Actor:       System Administrator
  AI Agent:    None
  ----
#4 | Cluster: Authentication & Access | Feature: User Login and Session
  Description: Authenticates the End User and establishes the session ownership context. Ensures every downstream feature scopes data strictly to the logged-in user.
  Workflow:
    1. User enters username and password on the login screen.
    2. System verifies credentials against the users table.
    3. On success, a session token is issued and ownership context is set.
    4. All subsequent requests filter data by the authenticated user_id.
    5. User can log out to end the session.
  Table:       user_sessions
  Columns:     session_id (varchar 64, pk), user_id (bigint, fk), issued_at (timestamp), expires_at (timestamp), ip_address (varchar 45), is_active (boolean)
  Actor:       End User
  AI Agent:    None
  ----
#5 | Cluster: Contact Intake | Feature: Create New Contact
  Description: Captures a brand-new contact record with full identity and organizational details. The starting point for all downstream list and activity workflows.
  Workflow:
    1. User opens the Contacts section and clicks New Contact.
    2. User fills first name, last name, email, phone, company, job title, address, and notes.
    3. System validates required fields and email/phone formats.
    4. System saves the record with owner_user_id and timestamps.
    5. New contact appears in the list view with a success message.
  Table:       contacts
  Columns:     contact_id (bigint, pk), owner_user_id (bigint, fk), first_name (varchar 100), last_name (varchar 100), email (varchar 255), phone (varchar 30), company (varchar 150), job_title (varchar 100), address (varchar 500), notes (text), created_at (timestamp), updated_at (timestamp)
  Actor:       End User
  AI Agent:    None
  ----
#6 | Cluster: Contact Intake | Feature: Duplicate Contact Detection
  Description: Prevents accidental duplicate entries by checking email against the user's existing contacts at save time. Improves data quality without blocking the user outright.
  Workflow:
    1. On contact save, system queries existing contacts owned by the same user.
    2. If an existing contact matches on email, a warning dialog is displayed.
    3. User chooses to proceed (creating a duplicate) or cancel.
    4. System logs the user's choice for audit.
  Table:       contacts
  Columns:     contact_id (bigint, pk), owner_user_id (bigint, fk), email (varchar 255, indexed), first_name (varchar 100), last_name (varchar 100), created_at (timestamp)
  Actor:       End User
  AI Agent:    None
  ----
#7 | Cluster: Contact Maintenance | Feature: Edit Contact Details
  Description: Allows the owning user to update any attribute of an existing contact. Tracks last-modified timestamps to support change visibility.
  Workflow:
    1. User opens a contact's detail page and clicks Edit.
    2. Form pre-populates with current values.
    3. User updates any field and clicks Save.
    4. System validates and persists changes, updating updated_at.
    5. Confirmation message is displayed.
  Table:       contacts
  Columns:     contact_id (bigint, pk), owner_user_id (bigint, fk), first_name (varchar 100), last_name (varchar 100), email (varchar 255), phone (varchar 30), updated_at (timestamp)
  Actor:       End User
  AI Agent:    None
  ----
#8 | Cluster: Contact Maintenance | Feature: Delete Contact
  Description: Permanently removes a contact along with its activity history and list memberships. Restricted to the contact owner to maintain privacy.
  Workflow:
    1. User selects Delete on a contact they own.
    2. System asks for confirmation.
    3. On confirm, system removes related list memberships and activities.
    4. Contact record is deleted from the contacts table.
    5. List views refresh and a success message is shown.
  Table:       contacts
  Columns:     contact_id (bigint, pk), owner_user_id (bigint, fk), deleted_at (timestamp), is_deleted (boolean)
  Actor:       End User
  AI Agent:    None
  ----
#9 | Cluster: List Organization | Feature: Create and Manage Contact Lists
  Description: Lets users define named groupings such as Clients, Vendors, or Friends to segment contacts. Provides full create-rename-delete control over the list catalog.
  Workflow:
    1. User opens the Lists section and clicks New List.
    2. User enters a list name and optional description.
    3. System saves the list with owner_user_id.
    4. User can rename or delete lists from the list management view.
    5. Deleting a list removes memberships only, not the underlying contacts.
  Table:       contact_lists
  Columns:     list_id (bigint, pk), owner_user_id (bigint, fk), list_name (varchar 150), description (varchar 500), created_at (timestamp), updated_at (timestamp)
  Actor:       End User
  AI Agent:    None
  ----
#10 | Cluster: List Organization | Feature: Add and Remove List Members
  Description: Manages the many-to-many relationship between contacts and lists. A single contact can belong to multiple lists for flexible segmentation.
  Workflow:
    1. User opens a list and clicks Add Contacts.
    2. User selects one or more existing contacts from a picker.
    3. System inserts rows into contact_list_members with added_at.
    4. User can remove a contact from the list at any time.
    5. Removal does not delete the contact record itself.
  Table:       contact_list_members
  Columns:     list_id (bigint, fk, pk), contact_id (bigint, fk, pk), added_at (timestamp), added_by_user_id (bigint, fk)
  Actor:       End User
  AI Agent:    None
  ----
#11 | Cluster: Activity Logging | Feature: Log Activity Against Contact
  Description: Records an interaction (call, email, meeting, note, or task) tied to a specific contact. Builds the historical interaction record used by the timeline view.
  Workflow:
    1. From the contact's detail page, user clicks Log Activity.
    2. User selects activity type from the catalog.
    3. User enters date/time, subject, description, and optional follow-up date.
    4. System validates required fields and saves the activity linked to the contact.
    5. Activity appears at the top of the contact's timeline.
  Table:       activities
  Columns:     activity_id (bigint, pk), contact_id (bigint, fk), activity_type_code (varchar 20, fk), subject (varchar 255), description (text), activity_date (timestamp), follow_up_date (date), created_by_user_id (bigint, fk), created_at (timestamp)
  Actor:       End User
  AI Agent:    None
  ----
#12 | Cluster: Activity Logging | Feature: Edit or Delete Activity
  Description: Lets the user who created an activity modify or remove it after the fact. Ensures the timeline stays accurate as users correct mistakes or update notes.
  Workflow:
    1. User locates the activity on a contact's timeline.
    2. User clicks Edit or Delete.
    3. For edit, form pre-populates and user submits changes.
    4. For delete, system asks for confirmation and removes the record.
    5. Timeline refreshes to reflect the change.
  Table:       activities
  Columns:     activity_id (bigint, pk), contact_id (bigint, fk), created_by_user_id (bigint, fk), subject (varchar 255), description (text), updated_at (timestamp), is_deleted (boolean)
  Actor:       End User
  AI Agent:    None
  ----
#13 | Cluster: Search & Review | Feature: Contact Search and Filter
  Description: Provides fast retrieval of contacts using free-text search and list-based filters. Essential for users managing thousands of contacts to quickly find a record.
  Workflow:
    1. User enters a search term in the contacts search bar.
    2. User optionally selects a list filter.
    3. System queries contacts by name, email, or company scoped to owner_user_id.
    4. Results are paginated and displayed in the list view.
    5. User clicks a result to open the contact detail page.
  Table:       contacts
  Columns:     contact_id (bigint, pk), owner_user_id (bigint, fk), first_name (varchar 100), last_name (varchar 100), email (varchar 255, indexed), company (varchar 150, indexed)
  Actor:       End User
  AI Agent:    None
  ----
#14 | Cluster: Search & Review | Feature: Contact Activity Timeline
  Description: Displays every logged interaction for a contact in reverse-chronological order. Gives users an at-a-glance history of the relationship.
  Workflow:
    1. User opens a contact's detail page.
    2. System loads all activities for the contact_id ordered by activity_date desc.
    3. Each timeline entry shows type, subject, date, and a snippet.
    4. User can expand an entry to view full details.
    5. User can jump to edit or follow-up actions from the timeline.
  Table:       activities
  Columns:     activity_id (bigint, pk), contact_id (bigint, fk, indexed), activity_type_code (varchar 20), subject (varchar 255), activity_date (timestamp, indexed), follow_up_date (date)
  Actor:       End User
  AI Agent:    None
  ----

--- DATA DICTIONARY (8 own tables, 0 referenced, 62 columns) ---
DB Prefix: contact_

## contact_users
   Stores user account credentials and profile information for authentication.
   - user_id : BIGINT UNSIGNED [PK · NOT NULL]
       Primary key for the user account.
   - username : VARCHAR(100) [NOT NULL · UNIQUE]
       Unique login name for the user.
   - email : VARCHAR(255) [NOT NULL · UNIQUE]
       User's email address used for login and notifications.
   - password_hash : VARCHAR(255) [NOT NULL]
       Hashed password value for authentication.
   - is_active : BOOLEAN [NOT NULL] DEFAULT 1
       Indicates whether the account is currently active.
   - created_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       Timestamp the account was created.
   - updated_at : TIMESTAMP
       Timestamp the account was last updated.

## contact_activity_types
   Lookup catalog of allowed activity categories such as Call, Email, Meeting, Note, and Task.
   - activity_type_code : VARCHAR(20) [PK · NOT NULL]
       Short code identifying the activity type (primary key).
   - display_name : VARCHAR(50) [NOT NULL]
       Human-readable label for the activity type.
   - description : VARCHAR(255)
       Optional explanation of when to use this activity type.
   - is_active : BOOLEAN [NOT NULL] DEFAULT 1
       Whether this activity type is selectable in the UI.
   - sort_order : INT [NOT NULL] DEFAULT 0
       Display ordering for activity type lists.

## contact_validation_rules
   Configurable validation rules applied to entity fields such as required, regex, or length checks.
   - rule_id : BIGINT UNSIGNED [PK · NOT NULL]
       Primary key for the validation rule.
   - entity_name : VARCHAR(50) [NOT NULL]
       Logical entity the rule applies to (e.g., contact, activity).
   - field_name : VARCHAR(50) [NOT NULL]
       Field within the entity the rule targets.
   - rule_type : VARCHAR(30) [NOT NULL]
       Type of rule, e.g., required, regex, max_length.
   - rule_value : VARCHAR(255)
       Parameter for the rule such as a regex pattern or length value.
   - error_message : VARCHAR(255) [NOT NULL]
       Message shown to the user when the rule fails.
   - is_active : BOOLEAN [NOT NULL] DEFAULT 1
       Whether the rule is currently enforced.

## contact_user_sessions
   Tracks active and historical login sessions issued to users.
   - session_id : VARCHAR(64) [PK · NOT NULL]
       Opaque session identifier (primary key).
   - user_id : BIGINT UNSIGNED [FK · NOT NULL] → users.user_id
       User the session belongs to.
   - issued_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       When the session was created.
   - expires_at : TIMESTAMP [NOT NULL]
       When the session is no longer valid.
   - ip_address : VARCHAR(45)
       Client IP captured at login (supports IPv6).
   - user_agent : VARCHAR(255)
       Browser or client user agent string.
   - is_active : BOOLEAN [NOT NULL] DEFAULT 1
       Whether the session is still valid.

## contact_contacts
   Core contact records owned by a user containing personal and professional details.
   - contact_id : BIGINT UNSIGNED [PK · NOT NULL]
       Primary key for the contact record.
   - owner_user_id : BIGINT UNSIGNED [FK · NOT NULL] → users.user_id
       User who owns this contact.
   - first_name : VARCHAR(100) [NOT NULL]
       Contact's given name (required).
   - last_name : VARCHAR(100) [NOT NULL]
       Contact's surname (required).
   - email : VARCHAR(255)
       Email address used for duplicate detection and search.
   - phone : VARCHAR(30)
       Contact phone number.
   - company : VARCHAR(150)
       Company or organization the contact is affiliated with.
   - job_title : VARCHAR(100)
       Contact's job title or role.
   - address : VARCHAR(255)
       Mailing or street address of the contact.
   - notes : TEXT
       Free-form notes about the contact.
   - is_deleted : BOOLEAN [NOT NULL] DEFAULT 0
       Soft-delete flag; true if the contact has been deleted.
   - deleted_at : TIMESTAMP
       When the contact was soft-deleted, if applicable.
   - created_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       When the contact was created.
   - updated_at : TIMESTAMP
       When the contact was last updated.

## contact_contact_lists
   User-defined lists used to group contacts by category such as Clients or Vendors.
   - list_id : BIGINT UNSIGNED [PK · NOT NULL]
       Primary key for the contact list.
   - owner_user_id : BIGINT UNSIGNED [FK · NOT NULL] → users.user_id
       User who owns the list.
   - list_name : VARCHAR(150) [NOT NULL]
       Name of the list shown in the UI.
   - description : VARCHAR(500)
       Optional description of the list's purpose.
   - is_deleted : BOOLEAN [NOT NULL] DEFAULT 0
       Soft-delete flag for the list.
   - created_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       When the list was created.
   - updated_at : TIMESTAMP
       When the list was last modified.

## contact_contact_list_members
   Join table associating contacts with the lists they belong to.
   - list_id : BIGINT UNSIGNED [PK · FK · NOT NULL] → contact_lists.list_id
       Reference to the contact list (composite PK).
   - contact_id : BIGINT UNSIGNED [PK · FK · NOT NULL] → contacts.contact_id
       Reference to the contact (composite PK).
   - added_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       When the contact was added to this list.
   - added_by_user_id : BIGINT UNSIGNED [FK · NOT NULL] → users.user_id
       User who added the contact to the list.

## contact_activities
   Activity log entries (calls, emails, meetings, notes, tasks) recorded against contacts.
   - activity_id : BIGINT UNSIGNED [PK · NOT NULL]
       Primary key for the activity record.
   - contact_id : BIGINT UNSIGNED [FK · NOT NULL] → contacts.contact_id
       Contact this activity was logged against.
   - activity_type_code : VARCHAR(20) [FK · NOT NULL] → activity_types.activity_type_code
       Type of activity (Call, Email, Meeting, Note, Task).
   - subject : VARCHAR(255) [NOT NULL]
       Short title or subject of the activity.
   - description : TEXT
       Detailed notes describing the activity.
   - activity_date : TIMESTAMP [NOT NULL]
       Date and time the activity occurred.
   - follow_up_date : DATE
       Optional date set for follow-up.
   - created_by_user_id : BIGINT UNSIGNED [FK · NOT NULL] → users.user_id
       User who logged the activity.
   - is_deleted : BOOLEAN [NOT NULL] DEFAULT 0
       Soft-delete flag for the activity.
   - created_at : TIMESTAMP [NOT NULL] DEFAULT CURRENT_TIMESTAMP
       When the activity record was created.
   - updated_at : TIMESTAMP
       When the activity record was last updated.

==================================================
 END OF STORY EXPORT
==================================================
