Cash Flow Minimizer - Modular Project Structure

📁 Project Organization

The project has been restructured into separate, modular files for better maintainability and code organization.

cash-flow-minimizer/
├── index.html                 # Main HTML file (clean structure)
├── styles.css                 # All CSS styling
├── README.md                  # This file
└── js/
    ├── data-structures.js     # Data structure implementations
    ├── app-state.js           # Global application state
    ├── algorithms.js          # Core optimization algorithms
    └── ui-functions.js        # DOM manipulation & event handlers

📚 File Descriptions

index.html

• Purpose: Clean HTML structure and semantic markup
• Contents:
  • Document meta tags and links to external resources
  • Page sections (Home, Algorithm, Code, Complexity, Implementation)
  • HTML form elements and containers
  • Script references to load JavaScript modules in correct order
• Size: Significantly reduced (~600 lines vs. 2300+ original)

styles.css

• Purpose: All visual styling and animations
• Contains:
  • CSS resets and global styles
  • Layout and component styles (cards, buttons, forms)
  • Animations and transitions
  • Responsive media queries
  • Color schemes and themes
• Size: ~1000 lines

js/data-structures.js

• Purpose: Custom data structure implementations
• Classes:
  • MinHeap - Min priority queue with O(log n) operations
  • MaxHeap - Max priority queue (extends MinHeap)
  • Graph - Adjacency list graph for transaction relationships
  • Stack - LIFO stack for undo/redo operations
  • StateManager - Manages undo/redo state history
• Key Features:
  • O(log n) heap operations (push, pop, peek)
  • Connected component detection
  • Complete state serialization for undo/redo

js/app-state.js

• Purpose: Global application state initialization
• Variables:
  • participants - Array of participant names
  • participantSet - Hash Set for O(1) lookups
  • transactions - Array of transaction objects
  • netBalance - Map of participant balances
  • minimizedTransactionsData - Optimized settlement transactions
  • transactionGraph - Graph of relationships
  • stateManager - Undo/redo manager instance
• Size: Minimal (~15 lines)

js/algorithms.js

• Purpose: Core optimization algorithms
• Functions:
  • minimizeTransactions() - Main O(n log n) optimization algorithm
  • displayGraphAnalysis() - Shows connected components
  • renderMinimizedTransactions() - Displays results
  • renderStatistics() - Shows performance metrics
• Algorithm: Greedy algorithm using actual heaps for O(n log n) complexity

js/ui-functions.js

• Purpose: All DOM manipulation and user interaction
• Functions:
  • showSection() - Navigation between pages
  • addParticipant() / removeParticipant() - Participant management
  • addTransaction() - Transaction entry
  • calculateBalances() / renderBalances() - Balance display
  • undoAction() / redoAction() - Undo/redo functionality
  • showVisualization() - Chart visualization
  • reset() - Clear all data
• Total: ~400 lines of pure UI logic

🎯 Benefits of Modular Structure

1. Separation of Concerns

Each file has a single, clear responsibility:

• Data structures are separate from UI
• Algorithms are independent of rendering
• State management is centralized

2. Easier Maintenance

• Finding and fixing bugs is faster
• Changes to styling don't affect logic
• Reduced cognitive load when reading code

3. Improved Readability

• Each file is focused and concise
• Function purposes are clear from context
• No massive 2300+ line files

4. Better Reusability

• Data structures can be used in other projects
• Algorithms can be tested independently
• UI functions can be refactored without affecting core logic

5. Scalability

• Easy to add new features
• Simple to create new visualization modules
• Can add more algorithms without bloating existing files

🔄 Script Load Order

Scripts must load in this specific order for proper functionality:

1. data-structures.js - Define MinHeap, MaxHeap, Graph, Stack, StateManager
2. app-state.js - Initialize global variables (uses classes from step 1)
3. algorithms.js - Define algorithm functions (uses classes and state from steps 1-2)
4. ui-functions.js - Define UI functions (uses everything from steps 1-3)

This order is already configured in index.html.

📊 File Statistics

File	Lines	Purpose
index.html	~600	HTML structure
styles.css	~1000	CSS styling
data-structures.js	~200	Data structure implementations
app-state.js	~15	Global state
algorithms.js	~80	Core algorithms
ui-functions.js	~400	UI & event handling
Total	~2300	Complete application

🚀 Running the Project

1. Open index.html in a web browser
2. All external resources (CSS, JS) will load automatically
3. No build process or compilation required

🔧 Development Tips

Adding a New Feature

1. Determine which file it belongs in
2. Add the function/class to the appropriate module
3. If it needs UI, add handlers to ui-functions.js
4. If it needs styling, add CSS to styles.css

Adding a New Data Structure

1. Create the class in data-structures.js
2. Initialize instances in app-state.js if globally needed
3. Use in algorithms or UI as needed

Debugging

• Open browser DevTools (F12)
• Check Console tab for errors
• Each module's functions are globally accessible
• State can be inspected via participants, transactions, etc.

📝 Code Quality

Maintained Standards

• ✅ Clear variable naming conventions
• ✅ Proper code organization
• ✅ Efficient algorithms (O(n log n) vs O(n² log n))
• ✅ Comprehensive comments in data-structures.js
• ✅ Responsive design maintained
• ✅ All features working as before

Performance Improvements

• Participant lookup: O(n) → O(1) using Hash Set
• Heap operations: O(n log n) sorting → O(log n) per operation
• Memory: Cleaner, more focused modules

📖 Example: How Modules Work Together

When user clicks "Optimize Transactions":

1. ui-functions.js calls minimizeTransactions()
2. algorithms.js uses MinHeap/MaxHeap from data-structures.js
3. Accesses global state from app-state.js
4. Saves state to stateManager for undo/redo
5. Calls rendering functions back in ui-functions.js

This clear separation makes the flow easy to understand and modify.