spotnotes.app/README.md

# SpotNotes

SpotNotes is a location-based note-taking web application. It allows users to drop notes on an interactive map, organize them into notepads, and optionally share them with the public or specific users.

## Features

- **Interactive Map:** View and create notes on a map powered by Leaflet and OpenStreetMap.
- **Location-Based Notes:** Every note is tied to specific geographic coordinates.
- **Notepads:** Organize notes into collections called "Notepads".
- **Privacy & Sharing:** Notepads can be private (only you), public (everyone), or shared via link tokens.
- **User Authentication:** Secure registration and login system.
- **Favorites:** Save and easily access your favorite public notepads.
- **Search & Geocoding:** Search through your notes or use geocoding to find locations worldwide.
- **Admin Dashboard:** Manage users, notepads, and notes.

## Tech Stack

- **Backend:** Python, Flask, Flask-SQLAlchemy (with SQLite for development/PostgreSQL for production).
- **Frontend:** HTML5, CSS3 (Vanilla), Vanilla JavaScript, Leaflet.js for maps.
- **Deployment:** Configured for Gunicorn and standard WSGI environments (includes `Procfile` and `gunicorn_config.py`).

## Project Structure

```
spotnotes.app/
│
├── app.py                  # Main application entry point
├── config.py               # Configuration settings
├── extensions.py           # Flask extensions (SQLAlchemy, CORS)
├── requirements.txt        # Python dependencies
│
├── blueprints/             # Flask Blueprints (Controllers)
│   ├── admin.py            # Admin dashboard routes
│   ├── api.py              # Main REST API for notes/notepads
│   ├── auth.py             # User authentication routes
│   ├── search.py           # Search and geocoding logic
│   └── static_routes.py    # Serving static HTML pages
│
├── models/                 # SQLAlchemy Database Models
│   ├── banned_ip.py        # Security model for IP bans
│   ├── favorite.py         # User's favorited notepads
│   ├── note.py             # Core note data structure
│   ├── notepad.py          # Collections of notes
│   └── user.py             # User account data
│
└── static/                 # Frontend Assets
    ├── index.html          # Main map interface
    ├── login.html          # Login page
    ├── register.html       # Registration page
    ├── admin.html          # Admin interface
    └── assets/
        ├── css/            # Modular stylesheets
        ├── js/             # Modular vanilla JS scripts
        └── images/         # Images and icons
```

## Getting Started

### Prerequisites

- Python 3.8+
- pip (Python package installer)

### Installation

1. **Clone the repository** (or download the source):
   ```bash
   git clone <repository-url>
   cd spotnotes.app
   ```

2. **Create a Virtual Environment (Optional but recommended):**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   ```

3. **Install Dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Run the Application:**
   ```bash
   python app.py
   ```
   The app will start on `http://127.0.0.1:5000/`. The database (`spotnotes.db`) will be created automatically upon the first run.

## Planned Features (Roadmap)

As detailed in the `GEMINI.md` file, the following features are actively planned or in development:

1. **Advanced Collaboration:** Share notepads with specific users granting explicit Read or Read/Write permissions.
2. **Content Editing:** Ability to edit existing notes and notepads.
3. **Rich Text & Multiline Notes:** Support for multiline text and bulleted lists.
4. **CSV Export:** Export all notes within a notepad to a `.csv` file.
5. **Location-Based Alerts:** Browser notifications when physically approaching a saved note.

## License

All rights reserved.