PROJECT_STRUCTURE.md

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! 🎉