A Full-stack Software Workflow
The repository connects device-facing APIs, authenticated data access, image storage, notifications, and dashboard views.
Device Event Intake
Device clients can submit structured delivery and access events through authenticated API endpoints.
Sensor Status
Sensor readings can be stored with event history and presented in the authenticated dashboard.
Device Activation
Device serial numbers connect incoming events to the correct owner after an explicit activation flow.
Evidence from Device to Dashboard
The prototype focuses on traceable events, ownership boundaries, and operator-visible status.
Access Event Records
Store timestamped device events so authenticated owners can review delivery and access history.
Image Evidence
Associate uploaded images with device events and serve them through an ownership-checked proxy.
Email Notification Path
Exercise an event-driven email path through Resend when the required hosted service configuration is available.
Designed for Architecture Evaluation
Use the prototype to examine how a mailbox monitoring system could serve several multi-unit environments.
Apartment Buildings
Model compartment ownership, delivery events, and resident access in a shared building.
HOA Communities
Explore role and ownership boundaries for shared community infrastructure.
New Construction
Evaluate API, storage, and dashboard integration before selecting or deploying physical devices.
Scope and Open Validation Work
Mail Guard is a software prototype. The repository demonstrates the application architecture. A real deployment requires validation with mailbox hardware, hosted services, monitoring, and incident response.
Prototype Questions
Clear boundaries make the implementation easier to evaluate.
What is implemented in this repository?
The project includes device-facing APIs, an authenticated dashboard, ownership checks, event and image records, email integration, and an experimental ESP32 firmware path.
Is this a deployable mailbox product?
No. It is an engineering prototype for evaluating the software architecture and device workflow, not a manufactured or production-validated mailbox system.
Which external services are required?
The full workflow depends on configured Clerk, MySQL, S3, and Resend services. The repository documents these dependencies and local setup requirements.
What has not been validated?
Production reliability, device durability, power behavior, sensor accuracy, connectivity, monitoring, incident response, and a complete security review remain open validation work.
Can the API be extended?
The current API demonstrates device events and dashboard data. Any third-party integration would require its own contract, authorization model, tests, and operational validation.
Which security boundaries are demonstrated?
The prototype includes Clerk sessions, device credentials, ownership-scoped reads and writes, verified database TLS, rate limiting, and authorized image access. These controls do not replace a production security review.