Arrangement Manager

A complete frontend-only web application for churches to generate seating arrangements and mass reading schedules automatically — with fairness, flexibility, and easy manual editing.

---

Table of Contents

1. Overview
2. Tech Stack
3. Project Structure
4. Getting Started
5. Module 1 — Refectory Seating
6. Module 2 — Mass Reading
7. Import / Export
8. Data Persistence
9. Keyboard Shortcuts
10. File Format Reference

---

Overview

Arrangement Manager contains two independent modules:

Module	Purpose
Refectory Seating	Assigns community members to tables, grouped strictly by gender, with overflow handling
Mass Reading	Generates fair rotating reading schedules for liturgical celebrations

Both modules support:

• Manual member entry
• JSON and Excel import
• Excel and PDF export
• Shuffle button
• Undo / Redo (50-step history)
• Manual editing via searchable dropdowns
• 14-day, 30-day, or custom duration

---

Tech Stack

Layer	Technology
Framework	React 18 + TypeScript
Build tool	Vite 5
UI library	Material UI v6
Routing	React Router v6
State management	Zustand 5 (localStorage persistence)
Form validation	React Hook Form + Zod
Animations	Framer Motion
Excel	xlsx (SheetJS)
PDF	jsPDF + jspdf-autotable
Dropdowns	React Select
Notifications	React Toastify

---

Project Structure

src/
├── components/
│   ├── common/          # Shared UI atoms
│   │   ├── ConfirmDialog.tsx
│   │   ├── EmptyState.tsx
│   │   ├── LoadingSkeleton.tsx
│   │   ├── PageHeader.tsx
│   │   ├── SearchableSelect.tsx
│   │   └── StatCard.tsx
│   └── layout/
│       └── AppShell.tsx  # Sidebar + topbar shell
├── pages/
│   ├── Dashboard.tsx
│   ├── ImportExport.tsx
│   ├── Settings.tsx
│   ├── seating/
│   │   ├── SeatingPage.tsx
│   │   └── components/
│   │       ├── ArrangementView.tsx
│   │       ├── CreateLayoutDialog.tsx
│   │       ├── MemberManager.tsx
│   │       └── TableCard.tsx
│   └── reading/
│       ├── ReadingPage.tsx
│       └── components/
│           ├── CreateScheduleDialog.tsx
│           ├── ReadingMemberManager.tsx
│           └── ScheduleView.tsx
├── store/
│   ├── seatingStore.ts   # Zustand store — Module 1
│   ├── readingStore.ts   # Zustand store — Module 2
│   └── settingsStore.ts  # App-wide settings
├── theme/
│   └── muiTheme.ts       # MUI theme (purple palette)
├── types/
│   └── index.ts          # All TypeScript interfaces
├── utils/
│   ├── exportUtils.ts    # Excel + PDF export/import helpers
│   ├── helpers.ts        # UUID, dates, shuffle utilities
│   ├── readingAlgorithm.ts
│   └── seatingAlgorithm.ts
├── styles/
│   └── global.css
├── App.tsx
└── main.tsx

---

Getting Started

Prerequisites

• Node.js 18+
• npm 9+

Install & Run

cd arrangement-manager
npm install
npm run dev

Open http://localhost:5173 in your browser.

Production Build

npm run build
npm run preview

---

Module 1 — Refectory Seating

Creating a Layout

1. Go to Refectory Seating in the sidebar
2. Click New Layout
3. Configure:
   • Layout title
   • Number of tables
   • Chairs per table
   • Members per table
   • Duration (14 days / 30 days / custom)
   • Starting gender (Male / Female / Random)

Adding Members

• Manual: Type name, select gender, press Add or Enter
• JSON import: [{ "name": "James", "gender": "Male" }]
• Excel import: Columns name, gender

Generating the Arrangement

Click Generate — the algorithm will:

1. Split members into Male and Female pools
2. Shuffle each pool randomly
3. Fill tables one gender at a time (no mixed-gender tables)
4. Create a Table 0 (Overflow) if members exceed total chair count
5. Set expiry date based on the configured duration

Business Rules

• Only one gender per table — no exceptions
• The configured starting gender fills tables first; the other gender follows
• If 80 chairs exist for 83 members → 3 overflow members go to Table 0
• After the duration expires, use Shuffle to reshuffle

Manual Editing

Each seat row has a searchable dropdown listing all eligible members. Selecting a member in a new seat automatically clears them from their previous seat — no duplicate assignments.

Shuffle / Undo / Redo

Action	Button
Re-randomise arrangement	Shuffle (⟳)
Undo last change	Undo (↩) — 50 steps
Redo undone change	Redo (↪)

---

Module 2 — Mass Reading

Creating a Schedule

1. Go to Mass Reading in the sidebar
2. Click New Schedule
3. Configure title, start date, and duration

Adding Readers

• No gender required
• Manual entry, JSON ([{ "name": "…" }]), or Excel (name column)

Generating the Schedule

Click Generate — the algorithm will:

1. Build three circular rotation queues (one per role)
2. Assign First Reading and Responsorial Psalm every day
3. Assign Second Reading only on Sundays — left blank on weekdays
4. Ensure everyone receives at least one assignment before repetition
5. Prevent the same member from holding two roles on the same day

Manual Editing

The schedule grid shows every day as a row. Each role column has a searchable dropdown for reassignment.

---

Import / Export

Export Formats

Module	Excel	PDF
Seating arrangement	✓	✓
Reading schedule	✓	✓

Import Formats

Module	Excel	JSON
Seating members	✓	✓
Reading members	✓	✓

Use the Import / Export page for bulk operations across any saved layout or schedule.

---

Data Persistence

All data is stored in browser localStorage — no backend, no server, no authentication.

localStorage key	Contents
am-seating	All seating layouts + members + arrangements
am-reading	All reading schedules + members + days
am-settings	Application settings

Note: Clearing browser data will erase all arrangements. Export to Excel/PDF for a permanent record.

---

File Format Reference

Seating Members Excel

name	gender
James	Male
Monica	Female

Reading Members Excel

name
James
Monica

Seating Members JSON

[
  { "name": "James",  "gender": "Male"   },
  { "name": "Monica", "gender": "Female" }
]

Reading Members JSON

[
  { "name": "James"   },
  { "name": "Monica"  }
]

---

Keyboard Shortcuts

Shortcut	Action
Enter in name field	Add member
Dropdown search	Type to filter members

---

Arrangement Manager v1.0 — Frontend only, no backend required.