Facilities Management Dashboard

Version: 1.2.4 (2025-04-27)

This project provides a full-stack Facilities Management Dashboard, designed to analyze and visualize maintenance and service request data from a MariaDB database. It consists of a Python FastAPI backend and a Flutter frontend.

Features

• Backend (FastAPI, Python):
  • Connects to a MariaDB database
  • Provides endpoints for statistics, trends, and preventative maintenance
  • Filters and aggregates data by month and year
  • Robust error handling and debug mode for development
• Frontend (Flutter):
  • Displays key statistics and trends in a user-friendly dashboard
  • Month/year picker for interactive analysis (NEW in 1.1.0)
• Date picker now limited to months with available data (NEW in 1.2.0)

Directory Structure

maintenance-summary/
├── backend/            # FastAPI backend
│   ├── main.py         # Main API application
│   ├── requirements.txt
│   └── ...
├── frontend/           # Flutter frontend app
│   └── ...
├── .env                # Environment variables (excluded from git)
├── .gitignore
├── README.md           # Project documentation
├── CHANGES.md          # Changelog
├── TODO.md             # Project tasks and roadmap
└── .windsurfrules      # IDE and workflow rules

MCP Servers and Tools Used

This project was built using the following MCP (Model Context Protocol) servers and tools:

MCP Servers

• filesystem MCP server: Provides file and directory operations for project automation and IDE features.
• github MCP server: Enables GitHub integration for issues, pull requests, and repository management.
• sequential-thinking MCP server: Powers advanced reasoning, planning, and multi-step workflow automation.
• brave-search MCP server: Adds web and local business search capabilities.

Tools Provided by MCP Servers

• File management (read, write, move, search, list, etc.)
• GitHub automation (issues, PRs, commits, repo management)
• Sequential thinking and problem-solving chains
• Web and local search
• Codebase and code item search
• Terminal command execution
• Browser preview for local web servers

For more details about MCP servers and their features, visit the Model Context Protocol website.

MCP Server Setup

The MCP (Model Context Protocol) server enables advanced IDE, automation, and AI assistant features for this project. To set up and use the MCP server:

1. Install MCP Server

   • Visit the Model Context Protocol website for installation instructions or use your preferred MCP server distribution.

2. Start the MCP Server

   • Run the MCP server in the root directory of your project:

     mcp-server --workspace .
     

   • Or, if using Docker:

     docker run -it -v $(pwd):/workspace -p 8080:8080 mcp/server:latest
     

3. Connect your IDE or AI assistant

   • Use an MCP-compatible client (see the list of supported clients) to connect to your running server.
   • Typical connection URL: http://localhost:8080

4. Troubleshooting

   • Ensure you have the necessary ports open.
   • Check logs for errors and consult the MCP documentation if needed.

---

Setup

Environment Variables

Unified Run Script

To start both backend and frontend services in one command:

chmod +x run
./run

Unified Run Script

1. Copy .env.sample to .env in the root directory and fill in the required values.
2. Ensure .env is excluded from version control.

Backend

1. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure your .env file with MariaDB credentials (see .env.example if provided).
4. Run the backend:

   uvicorn main:app --reload --port 8000
   

Frontend

1. Install Flutter if not already installed.
2. Navigate to the frontend directory.
3. Run the app:

   flutter run
   

Git & Security

• .env and development artifacts are excluded from git (see .gitignore).
• Do not commit secrets or credentials.

Project Management

• Track changes with a version number in the README.md file (major.minor.patch format)
• Always update the README.md file with any changes made to the codebase
• Document changes between versions in CHANGES.md
• Add new feature requests/changes to TODO.md
• Strikethrough items from the TODO.md list that are done, include the version number

Contributing

Pull requests and feature suggestions are welcome!

License

Specify your license here (MIT, Apache 2.0, etc.)

---

For more details, see the source code in backend/ and frontend/.