Lagomare Gates

A web-based gate access management and control system. Authorized users can remotely open physical gates via a mobile-friendly PWA. An admin dashboard provides full management of gates, access codes, and users.

Features

• Keypass authentication — users authenticate with an access code; each keypass can have a per-gate allowlist, an optional expiration date, and an optional time/day-of-week schedule
• Keypass schedules — restrict a keypass to specific days of the week and/or a time window (e.g. Monday–Friday 08:00–18:00, server local time)
• Remote gate control — integrates with AVConnect and Shelly Cloud to trigger gate macros/relays
• Gate icons — each gate can be assigned any UTF-8 character or emoji as its icon, displayed on the user app button and keypass selector
• Role-based admin panel — two roles (admin, manager) with different permission levels
• Two-factor authentication (TOTP) — admins can enable app-based 2FA (Google Authenticator, Authy, etc.) on their account
• Access audit log — every open attempt is logged with timestamp, keypass, gate, IP, and result; filterable and paginated
• Keypass QR codes — generate a scannable QR code for each keypass; scanning opens the PWA and logs in automatically
• Keypass code options — choose character set (alphanumeric, alpha, numeric, or a 4-word passphrase) and length when auto-generating codes
• Telegram notifications — optional push notifications to a Telegram group whenever a gate is opened
• Progressive Web App — installable on mobile devices with offline caching

Tech Stack

Layer	Technology
Backend	FastAPI + Uvicorn
ORM	SQLAlchemy
Database	SQLite
Auth	JWT (HS256) + bcrypt
2FA	TOTP (RFC 6238) via pyotp
Credential storage	Fernet symmetric encryption
Gate integration	AVConnect HTTP API / Shelly Cloud API
Notifications	Telegram Bot API
QR generation	qrcode + Pillow
Frontend	Vanilla JS PWA

Project Structure

src/
├── main.py               # App entry point, startup, static file serving
├── core/
│   ├── auth.py           # JWT creation/verification, password hashing
│   ├── config.py         # Settings loaded from environment variables
│   ├── database.py       # SQLAlchemy models and DB initialization
│   ├── dependencies.py   # FastAPI dependency injection (auth guards)
│   └── schemas.py        # Pydantic request/response schemas
├── routers/
│   ├── auth.py           # POST /api/auth/admin, POST /api/auth/keypass
│   ├── gates.py          # User-facing gate list and open endpoints
│   ├── keypasses.py      # Admin keypass CRUD + QR code generation
│   ├── admins.py         # Admin user management
│   ├── credentials.py    # AVConnect credential management
│   ├── stats.py          # Access log / statistics (paginated, filtered)
│   └── telegram.py       # Telegram notification configuration
├── services/
│   ├── avconnect.py      # AVConnect API client
│   ├── gates.py          # Gate open orchestration
|   |── shelly.py         # Shelly Cloud API client
│   └── telegram.py       # Telegram Bot API client
└── static/               # Frontend PWA (index.html, admin.html, JS, CSS)
data/
└── gates.db              # SQLite database (auto-created on first run)

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/auth/admin	Admin login — returns JWT
POST	/api/auth/keypass	Keypass login — returns JWT

User (keypass token required)

Method	Endpoint	Description
GET	/api/gates	List gates accessible to the authenticated keypass
POST	/api/gates/{gate_id}/open	Open a gate

Admin — Gates (manager+)

Method	Endpoint	Description
GET	/api/admin/gates	List all gates
POST	/api/admin/gates	Create a gate (admin only)
PUT	/api/admin/gates/{gate_id}	Update a gate (admin only)
DELETE	/api/admin/gates/{gate_id}	Delete a gate (admin only)
POST	/api/admin/gates/{gate_id}/open	Manually open a gate

Admin — Keypasses (manager+)

Method	Endpoint	Description
GET	/api/admin/keypasses	List all keypasses
POST	/api/admin/keypasses	Create a keypass
PATCH	/api/admin/keypasses/{kp_id}	Update a keypass (description, expiry, gates, schedule)
DELETE	/api/admin/keypasses/{kp_id}	Revoke a keypass
GET	/api/admin/keypasses/{kp_id}/qr	Download QR code PNG for a keypass

Admin — Users (admin only)

Method	Endpoint	Description
GET	/api/admin/admins	List admin users
POST	/api/admin/admins	Create an admin user
DELETE	/api/admin/admins/{username}	Delete an admin user
PATCH	/api/admin/admins/{username}/password	Change password
POST	/api/admin/admins/{username}/totp/setup	Generate a new TOTP secret and return provisioning URI + QR
POST	/api/admin/admins/{username}/totp/enable	Verify a TOTP code and activate 2FA
DELETE	/api/admin/admins/{username}/totp	Disable 2FA and discard the secret

Admin — AVConnect Credentials (admin only)

Method	Endpoint	Description
GET	/api/admin/credentials/avconnect	View stored AVConnect credentials
PUT	/api/admin/credentials/avconnect	Create or update AVConnect credentials
GET	/api/admin/credentials/shelly	View stored Shelly Cloud credentials
PUT	/api/admin/credentials/shelly	Create or update Shelly Cloud credentials
GET	/api/admin/credentials/mock	Get mock mode status
PUT	/api/admin/credentials/mock	Enable or disable mock mode

Admin — Statistics (manager+)

Method	Endpoint	Description
GET	/api/admin/stats	Paginated, filtered access log

Query parameters: gate_id, keypass_code (partial match), success (bool), date_from, date_to, page (default 1), page_size (default 50, max 200).

Admin — Telegram Notifications (admin only)

Method	Endpoint	Description
GET	/api/admin/telegram	Get current Telegram configuration
PUT	/api/admin/telegram	Save bot token and chat ID
POST	/api/admin/telegram/test	Send a test message

Configuration

All settings are read from environment variables (centralised in src/core/config.py).

Security

Variable	Default	Description
SECRET_KEY	(required)	JWT signing key and Fernet encryption key. The application will refuse to start if this is not set. Use a long random string (openssl rand -hex 32).

Admin seed account

Variable	Default	Description
ADMIN_USERNAME	admin	Username for the initial admin account created on first run.
ADMIN_PASSWORD	(none)	Password for the initial admin account. If unset, no seed account is created. Minimum 12 characters.

Server

Variable	Default	Description
APP_PORT	8000	HTTP port the server listens on.

Database

Variable	Default	Description
DATABASE_URL	sqlite:///data/gates.db	SQLAlchemy database URL.

Map (home location)

Variable	Default	Description
HOME_LAT	(none)	WGS-84 latitude of the home/property marker shown on the frontend map.
HOME_LON	(none)	WGS-84 longitude of the home/property marker.
HOME_NAME	Home	Display name for the home marker popup.

If HOME_LAT and HOME_LON are both set, the map is always visible. If only gates have coordinates (set per-gate in the admin panel), the map is shown only when at least one gate has a location.

Network / reverse proxy

Variable	Default	Description
CORS_ORIGINS	(empty — no cross-origin requests)	Comma-separated list of allowed CORS origins, e.g. https://gates.example.com.
TRUSTED_PROXY_IPS	127.0.0.1	Comma-separated list of reverse-proxy IPs whose X-Forwarded-For header is trusted for client IP resolution.

Logging

Variable	Default	Description
LOG_LEVEL	INFO	Logging verbosity. One of DEBUG, INFO, WARNING, ERROR, CRITICAL.
LOG_FILE	/var/log/lagomaregates.log	Path to the rotating log file (10 MB, 5 backups). Set to an empty string to disable file logging.

Running with Docker Compose

# Copy and edit the compose file to set your SECRET_KEY
docker compose up -d

The default docker-compose.yml starts the service on port 8000. Set a strong SECRET_KEY and, optionally, ADMIN_USERNAME / ADMIN_PASSWORD before deploying.

The ./data directory is mounted into the container so the SQLite database persists across restarts.

Running Locally

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export SECRET_KEY="$(openssl rand -hex 32)"
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="changeme-at-least-12"

uvicorn src.main:app --port 8000

The application is then available at:

• User interface — http://localhost:8000/
• Admin dashboard — http://localhost:8000/admin

AVConnect Integration

Gates are controlled through one of two supported API providers.

AVConnect

Each gate is mapped to an AVConnect macro ID. When a gate open request is received, the service:

1. Authenticates with AVConnect using the stored credentials (session is cached in the database)
2. Executes the configured macro for the gate

Credentials (password) are stored encrypted in the database using Fernet symmetric encryption derived from SECRET_KEY.

Shelly Cloud

Each gate is mapped to a Shelly device ID. The service calls the Shelly Cloud API with the stored auth key to activate the device's relay.

The Shelly server URI and auth key are stored encrypted. Configure them under Admin → Credentials → Shelly Cloud.

Mock mode — when enabled via the admin dashboard, gate open requests always succeed without contacting any external API. Useful for testing.

Keypass Schedules

In addition to an expiry date and a per-gate allowlist, each keypass can be restricted to a configurable time window:

• Days of the week — select any combination of Mon–Sun. If no day is checked the restriction applies on any day.
• Time window — a From / To time in 24-hour format (server local time). Both values must be provided together.

When a keypass with a schedule is used outside its allowed window the API returns HTTP 403 (Keypass is not valid today / Keypass is not valid at this time) and the gate will not open. The restriction is enforced in require_keypass in src/core/dependencies.py.

The schedule is stored as a JSON object in the schedule column of the keypasses table:

{ "days": [0, 1, 2, 3, 4], "time_start": "08:00", "time_end": "18:00" }

days uses Python's weekday() convention: 0 = Monday, 6 = Sunday. Any absent key is treated as unrestricted (e.g. omitting days means any day is allowed).

Keypass QR Codes

Each active keypass has a QR button in the admin panel. Clicking it generates a PNG QR code that encodes the URL:

https://<your-domain>/?k=<KEYPASS_CODE>

Scanning the code with a phone opens the web app and logs in automatically. If the keypass is expired or revoked, the user is shown an error on the login screen.

Telegram Notifications

Configure a Telegram bot to receive a message in a group or chat every time a gate is opened:

1. Create a bot via @BotFather and copy the token
2. Add the bot to your group and obtain the chat ID (e.g. using @userinfobot)
3. Open Admin → Notifications, enter the token and chat ID, and click Save
4. Use Send test message to verify the setup

Notifications are sent in a background thread and never block the gate open response. Failures are logged as warnings and do not affect gate operation.

Two-Factor Authentication (TOTP)

Each admin account can independently enable TOTP-based two-factor authentication:

1. Open Admin → Admin Users and click Enable 2FA on your own row
2. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
3. Enter the 6-digit code to confirm — 2FA is only activated after a successful verification
4. On subsequent logins, after entering your password you will be prompted for the current TOTP code

To disable, click Disable 2FA on your row and confirm.

Only the account owner can enable or disable their own 2FA. TOTP secrets are stored Fernet-encrypted in the database.

Roles

Role	Permissions
admin	Full access — all endpoints including gate/user/credential/notification management
manager	Gate open, keypass management, statistics — cannot manage admin users, AVConnect credentials, gate configuration, or Telegram settings