# Project Structure

```
participatory_planner/
│
├── 📱 app/                          # Main application package
│   ├── __init__.py                  # Flask app initialization
│   ├── analyzer.py                  # 🤖 AI model for classification (FREE!)
│   │
│   ├── models/
│   │   └── models.py                # Database models (Token, Submission, Settings)
│   │
│   ├── routes/
│   │   ├── auth.py                  # Login, logout, token generation
│   │   ├── submissions.py           # Contribution submission
│   │   └── admin.py                 # Admin dashboard & API endpoints
│   │
│   ├── templates/                   # HTML templates (Jinja2)
│   │   ├── base.html                # Base template
│   │   ├── login.html               # Login page
│   │   ├── generate.html            # Token generation page
│   │   ├── submit.html              # Submission form
│   │   │
│   │   └── admin/                   # Admin templates
│   │       ├── base.html            # Admin base template
│   │       ├── overview.html        # Dashboard overview
│   │       ├── registration.html    # Registration management
│   │       ├── tokens.html          # Token management
│   │       ├── submissions.html     # All submissions view
│   │       └── dashboard.html       # Analytics & visualizations
│   │
│   └── static/                      # Static files (auto-created)
│       ├── css/
│       └── js/
│
├── 🚀 run.py                        # Application entry point
│
├── 📦 requirements.txt              # Python dependencies
├── 🔒 .env.example                  # Environment variables template
├── .gitignore                       # Git ignore rules
│
├── 📚 Documentation
│   ├── README.md                    # Full documentation
│   ├── QUICKSTART.md                # Quick start guide
│   ├── AI_MODEL_COMPARISON.md       # AI model options
│   └── PROJECT_STRUCTURE.md         # This file
│
├── 🧪 test_analyzer.py              # Test script for AI model
│
└── 💾 Database (auto-created on first run)
    └── instance/
        └── participatory_planner.db # SQLite database

```

## Key Components

### 🤖 AI Analyzer (`app/analyzer.py`)
- **Free Hugging Face model** - No API keys needed!
- Zero-shot classification using `facebook/bart-large-mnli`
- Categories: Vision, Problem, Objectives, Directives, Values, Actions
- Runs completely offline after first download

### 🗃️ Database Models
- **Token**: User authentication tokens
- **Submission**: Participant contributions
- **Settings**: Application configuration

### 🎨 Frontend
- **Bootstrap 5**: Responsive UI
- **Leaflet.js**: Interactive maps
- **Chart.js**: Data visualizations
- **Jinja2**: Server-side templating

### 🔌 API Endpoints
- Public routes (login, registration)
- Contributor routes (submission)
- Admin routes (dashboard, analytics, export)

## Data Flow

```
1. Participant → Generate Token → Get unique access code
2. Participant → Login → Submit ideas (with optional location)
3. Admin → Analyze → AI categorizes submissions
4. Admin → View Analytics → Charts, maps, categorized data
5. Admin → Export → JSON/CSV for analysis
```

## File Sizes

- **Source code**: ~50KB
- **Dependencies**: ~500MB (including PyTorch & Transformers)
- **AI Model**: ~1.5GB (one-time download, cached locally)
- **Database**: Grows with submissions (very small, ~few MB typically)

## Technology Stack

| Component | Technology | Why? |
|-----------|-----------|------|
| Backend | Flask | Lightweight, easy to deploy |
| Database | SQLite | Simple, no setup needed |
| ORM | SQLAlchemy | Clean database operations |
| AI Model | Hugging Face | Free, offline, privacy-focused |
| Frontend | Bootstrap 5 | Responsive, modern UI |
| Maps | Leaflet.js | Free, powerful mapping |
| Charts | Chart.js | Simple, beautiful charts |

## Deployment Ready

✅ Production-ready Flask setup
✅ Environment variables for config
✅ Database migrations ready
✅ No external API dependencies
✅ Completely self-contained

Happy participatory planning! 🎉