PSTA Expense Tracker

A modern, easy-to-use web app for tracking PSTA-related expenses, built with Flask.

---

🚀 Recent Changes (May 2025)

• Migrated user-facing pages (Profile, base.html, etc.) from Bootstrap to Tailwind CSS and Alpine.js for a modern, responsive UI.
• Updated Jinja2 macros and form helpers to use explicit arguments (no **kwargs), ensuring compatibility with Jinja2.
• Fixed database migration drift (especially for SQLite): clarified process for handling pre-existing tables and schema changes.
• Improved admin and search endpoints to use correct Flask endpoint names.
• Cleaned up template code, removed legacy conditional logic, and improved sidebar and navigation.
• Resolved blockers related to missing DB columns and migration errors.

📁 Project Directory Structure (Reference)

psta_expense/
├── app/
│   ├── __init__.py
│   ├── forms.py
│   ├── extensions.py
│   ├── models/
│   │   ├── user.py
│   │   ├── school.py
│   │   └── ...
│   ├── routes/
│   │   ├── expense.py
│   │   └── ...
│   ├── templates/
│   │   ├── base.html
│   │   ├── expense/
│   │   │   └── mileage_submit.html
│   │   └── ...
│   └── utils/
│       └── ...
├── static/
│   ├── js/
│   │   ├── mileage_map.js
│   │   └── expense_form.js
│   ├── style.css
│   └── images/
├── docs/
│   ├── README.md
│   └── ...
├── requirements.txt
├── instance/
│   └── database.db
└── ...

• Python code: app/ (models, routes, forms, utils)
• Templates: app/templates/ (HTML files, organized by feature)
• Static files: static/ (JS, CSS, images)
• Documentation: docs/

When adding new static files, templates, or Python modules, reference this outline to ensure correct placement and import/reference paths.

🛣 Project Status

• Active Development — See ROADMAP.md for upcoming features.
• UI Stack: Now using Tailwind CSS and Alpine.js for all user-facing pages. Bootstrap has been removed from user templates.
• Milestone: Expense claim preview/edit workflow is robust and stable. All data fields are preserved across preview and edit.
• Known Limitations:
  • Receipt upload is not yet persisted or viewable in preview; file must be re-attached if editing.
  • Receipt will be required only for categories that require it (to be implemented in category backend).
  • Mileage form: start/end address fields don't clear after adding a leg, 'usual commute' field doesn't allow decimal input.
  • [Planned Cleanup] The 'username' field in the User model is unused and will be removed after all features are stable.

✨ Key Features

User Calendar Integration

• Users can now import events directly into their calendar application (iCal/Google Calendar) via a download link on the events page. This makes it easy to keep track of upcoming meetings and events.

Recent Improvements

• Admin sidebar now shows a single Home link (no submenu) when on admin pages for a cleaner UI.
• Admins can view all claims in a sortable and filterable table (filter by claimant, category, payment method; sort by date, claimant, category, amount).
• Claims, schools, and members admin pages now all use a consistent Bootstrap table style for better UX.
• Each claim in the admin claims table links directly to its detail page for faster review.
• Profile page layout cleaned up: Name and photo with action buttons are now side-by-side, all fields are single-instance, and the design is clean and user-friendly.

Next Planned Features

• Mileage Claim:
  • Address autocomplete for start/end locations using Google Maps.
  • Automatic distance calculation using Google Maps.
  • 'Usual commute' calculation and subtraction from total mileage.
  • Implement minimum claim amount.
  • Fix: Start/end address fields should clear after adding a leg.
  • Fix: 'Usual commute' field should allow decimal input.
• Admin Dashboard:
  • Collapsible onboarding checklist for new admins.
  • Statistics table (member counts, school counts, etc.).
• Schools Page:
  • Display staff count per school.
  • List recently modified school staff.
• Category Details:
  • Add description and receipt-needed fields to each category.
  • (Planned) Add a new table to track budget amount for each category per financial year.

🛠 Technical Breakdown

Migration & Troubleshooting Tips

• If you see errors like table already exists during flask db upgrade, check your migrations for duplicate table creation and edit migration scripts to skip already-existing tables (especially with SQLite).
• Jinja2 macros must use explicit arguments (not **kwargs). Update your _formhelpers.html macros accordingly.
• All user-facing templates now use Tailwind and Alpine.js for styling and interactivity.

---

🛠 Technical Breakdown: Member Inquiry Email-to-Issue & Knowledge Base

Note: When building the initial knowledge base for member Q&A, we will use a spreadsheet of previous member questions to seed the database for better search and auto-answer coverage.

1. Email Ingestion

• System receives member inquiries via a dedicated email address (e.g., support@domain.com) or via email forwarding.
• Emails are fetched using IMAP/POP3 or an email API (e.g., Gmail API).

2. LLM Parsing

• The full email thread (including replies) is parsed using a Large Language Model (LLM).
• The LLM extracts:
  • The main question/issue
  • Relevant user information
  • The full Q&A thread (for context)

3. Issue Tracking

• Parsed issues are saved to the database and linked to the corresponding user.
• Admins can view and manage issues on each user’s admin page (e.g., /admin/users/2).

4. Anonymized Knowledge Base

• The Q&A thread is anonymized (removing names/emails) and stored in a searchable knowledge base.
• This knowledge base can be used to auto-suggest answers for future member questions.

5. Admin UI Integration

• Admin dashboard shows issues per user and provides a search interface for the anonymized knowledge base.

• Future: Option to train the LLM on the knowledge base for improved auto-responses.

• Modern event calendar layout on the homepage (date/time and event details cleanly separated)

• Removed redundant 'Edit My Details' and 'Submit a Claim' buttons from the homepage (now in the main menu)

• Upcoming: Admin event editor and Google Calendar integration (subscribe to one or more calendars to display events)

• User Registration & Login

• Admin Dashboard for managing users, expenses, and categories

• Dynamic Expense Submission Form

  • Add multiple itemized entries per claim
  • Fields update automatically based on expense type (e.g., mileage, meals, office supplies)
  • Live mileage calculation
  • Receipt upload

• Detailed Reporting (per item, per category, per user)

• Bootstrap UI with branded navigation and icons

• School & Staff Management (admins can manage schools and contacts)

• Secure Authentication (admin/user roles, password reset)

🏗️ Coming Soon

• Fixed Expense Types (not user-editable; ensures consistency and correct dynamic fields)
• Even Smarter Dynamic Fields (form will show only the fields needed for each expense type)
• Expense History Page
• Advanced Admin Reporting

🛠️ Setup

Running the Server on Another Computer (Step-by-Step)

1. Clone the repository on the target computer:

   git clone <your-repo-url>
   cd psta_expense
   

2. Create and activate a Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set environment variables:
   • You can use a .env file or export variables in your shell. At minimum, set:
     • FLASK_APP=app:create_app
     • FLASK_DEBUG=1 (for development)
     • GOOGLE_MAPS_API_KEY=<your-api-key> (required for mileage form)
   • Example .env file:

     FLASK_APP=app:create_app
     FLASK_DEBUG=1
     GOOGLE_MAPS_API_KEY=your-key-here
     

   • To load from .env, install python-dotenv (already in requirements.txt) and Flask will auto-load it.
5. Initialize the database and seed data:
   • The database will be created automatically on first run.
   • To seed default categories:

     flask seed-categories
     

   • To add an admin user:

     flask add-admin --email you@example.com --password yourpass
     

6. (Optional) Update Google Maps API Key in the App:
   • You can also set the Google Maps API key in the admin settings UI or directly in the database/settings if needed.
7. Run the development server, accessible from other computers:

   flask run --host=0.0.0.0 --port=5100
   

   • This will make the app available on your local network at http://<your-computer-ip>:5100.
   • Find your computer's IP with ipconfig (Windows) or ifconfig/ip a (Linux/Mac).
8. Network/Firewall:
   • Make sure your firewall allows inbound connections on port 5100.
   • Other computers on the same network can access the app using http://<your-computer-ip>:5100.

---

1. Clone the repository:

---

🤖 LLM/Developer Handoff

This project is designed for easy onboarding by both human developers and LLM coding assistants.

• All business logic is in app/routes/, forms in app/forms/, templates in app/templates/.
• Use the ROADMAP.md for prioritized tasks and feature context.
• Follow the “Next Priorities” in this README or the roadmap for immediate engineering focus.
• When in doubt, review the codebase for docstrings and inline comments.
• A technical debt/cleanup task is planned: remove the unused 'username' field from the User model and all related UI/backend references after all core features are complete.

For LLMs:

• Always preserve data integrity and user experience.
• Use modular, readable code and keep UI/UX clear.
• If unsure about a requirement, check ROADMAP.md or this README for guidance.

🧑‍💻 How to Contribute/Extend

• Fork and branch before making changes.

• Use descriptive commit messages.

• Test locally before submitting PRs.

  git clone <your-repo-url>
  cd psta_expense
  

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set environment variables:

   export FLASK_APP=app:create_app
   export FLASK_DEBUG=1 # For development
   

5. Initialize database and seed data:
   • The database will be created automatically. To reset, delete instance/database.db.
   • Seed default categories:

     flask seed-categories
     

   • Add an admin user:

     flask add-admin --email you@example.com --password yourpass
     

🔒 Admin Quick Tips

• Use the dashboard to manage users, schools, and categories
• All expense items are stored individually for detailed reporting

📄 For More Details

• See ROADMAP.md for the latest planned features and development phases.

---

Easy to use. Powerful for admins. Built for PSTA.

    flask seed-categories
    ```
*   Add an admin user:
    ```bash
    flask add-admin <username> <email>
    # Follow prompts for password
    ```
    - If a user with the given username or email already exists, this command will update their password and admin status instead of failing. You will see a message indicating whether the user was created or updated.

6. Run the development server:

   flask run
   

7. Access the application at http://127.0.0.1:5100 (or the address provided by Flask).

Admin Login & Troubleshooting

• Seeded Admin User:
  • If you use the test data seeding script (scripts/seed_test_data.py), the seeded admin account is:
    • Email: president@psta.ca
    • Username: admin
    • Password: testpass
• Resetting Admin Password:
  • You can update any admin user's password and admin status using:

    flask add-admin <username> <email>
    # You will be prompted for a new password.
    

  • This works whether the user exists or not (it will update or create as needed).
• Cannot Login?
  • Make sure you are using the correct email and password. If you have run the seed script after creating an admin, the password may have been reset to testpass.
  • Use flask add-admin to reset the password as above.

Usage

• Navigate to the application URL.
• Admin users can access the /admin dashboard.
• (Future) Users will be able to submit expenses via /expense/submit.

Contributing

(Add contribution guidelines if applicable)

License

(Add license information if applicable)