Parking Manager

A manager-centric parking spot management application with fair assignment algorithm.

Features

• Manager-centric model: Managers own parking spots, not offices
• Fair assignment algorithm: Users with lowest parking/presence ratio get priority
• Presence tracking: Calendar-based presence marking (present/remote/absent)
• Closing days: Support for specific dates and weekly recurring closures
• Guarantees & exclusions: Per-user parking rules
• Authelia/LLDAP integration: SSO authentication with group-based roles

Architecture

├── app/
│   ├── routes/          # API endpoints
│   │   ├── auth.py      # Authentication + holidays
│   │   ├── users.py     # User management
│   │   ├── managers.py  # Manager rules (closing days, guarantees)
│   │   ├── presence.py  # Presence marking
│   │   └── parking.py   # Parking assignments
│   └── config.py        # Application configuration
├── database/
│   ├── models.py        # SQLAlchemy ORM models
│   └── connection.py    # Database setup
├── services/
│   ├── auth.py          # JWT + password handling
│   ├── parking.py       # Fair assignment algorithm
│   ├── holidays.py      # Public holiday calculation
│   └── notifications.py # Email notifications (TODO: scheduler)
├── frontend/
│   ├── pages/           # HTML pages
│   ├── js/              # JavaScript modules
│   └── css/             # Stylesheets
└── main.py              # FastAPI application entry

Quick Start (Development)

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run development server
python main.py

Access at http://localhost:8000

Docker Deployment

# Build image
docker build -t parking-manager .

# Run with environment variables
docker run -d \
  -p 8000:8000 \
  -v ./data:/app/data \
  -e SECRET_KEY=your-secret-key \
  -e AUTHELIA_ENABLED=true \
  parking-manager

Or use Docker Compose:

docker compose up -d

Environment Variables

Variable	Description	Default
SECRET_KEY	JWT signing key	Random (dev only)
HOST	Bind address	0.0.0.0
PORT	Server port	8000
DATABASE_URL	SQLite path	sqlite:///data/parking.db
AUTHELIA_ENABLED	Enable Authelia SSO	false
ALLOWED_ORIGINS	CORS origins	*

SMTP (Notifications - Optional)

Variable	Description
SMTP_HOST	SMTP server hostname
SMTP_PORT	SMTP port (default: 587)
SMTP_USER	SMTP username
SMTP_PASSWORD	SMTP password
SMTP_FROM	From email address

Authentication

Standalone Mode

Built-in JWT authentication with bcrypt password hashing. Users register/login via /login and /register.

Authelia Mode

When AUTHELIA_ENABLED=true, the app trusts Authelia headers:

• Remote-User: User email/username
• Remote-Name: Display name
• Remote-Groups: Comma-separated group list

Group mapping (follows lldap naming convention):

• parking_admins → admin role
• managers → manager role
• Others → employee role

User Roles

Role	Permissions
admin	Full access, manage users and managers
manager	Manage their team, set parking rules
employee	Mark own presence, view calendar

API Endpoints

Authentication

• POST /api/auth/login - Login
• POST /api/auth/register - Register (standalone mode)
• POST /api/auth/logout - Logout
• GET /api/auth/me - Current user info
• GET /api/auth/holidays/{year} - Public holidays

Users

• GET /api/users - List users (admin)
• POST /api/users - Create user (admin)
• PUT /api/users/{id} - Update user (admin)
• DELETE /api/users/{id} - Delete user (admin)
• GET /api/users/me/profile - Own profile
• PUT /api/users/me/settings - Own settings

Managers

• GET /api/managers - List managers
• GET /api/managers/{id} - Manager details
• PUT /api/managers/{id}/settings - Update parking quota (admin)
• GET/POST/DELETE /api/managers/{id}/closing-days - Specific closures
• GET/POST/DELETE /api/managers/{id}/weekly-closing-days - Recurring closures
• GET/POST/DELETE /api/managers/{id}/guarantees - Parking guarantees
• GET/POST/DELETE /api/managers/{id}/exclusions - Parking exclusions

Presence

• POST /api/presence/mark - Mark presence
• POST /api/presence/mark-bulk - Bulk mark
• GET /api/presence/my-presences - Own presences
• GET /api/presence/team - Team calendar (manager/admin)

Parking

• GET /api/parking/assignments/{date} - Day's assignments
• GET /api/parking/my-assignments - Own assignments
• POST /api/parking/manual-assign - Manual assignment
• POST /api/parking/reassign-spot - Reassign spot

Fairness Algorithm

Parking spots are assigned based on a fairness ratio:

ratio = parking_days / presence_days

Users with the lowest ratio get priority. Guaranteed users are always assigned first.

License

MIT