residential-amenities-platform

Residential Amenities Platform

Private-source, cloud-hosted platform for residential amenity reservations, payments and administration.

Project status: Backend MVP, MVP product client and Phase 6 UX/security extensions are implemented and covered by CI (issues #3-#27, #44-#55, #62, #66, #76-#80, #87-#94 and #103). Discovery/business-policy issue #2 is closed. Phase 7 cloud engineering is running in Azure staging: Terraform-managed infrastructure, OIDC delivery, ACR image pushes, Container Apps revisions and end-to-end smoke checks are all validated. Pilot scope: one residential building with 10 units (1A–5B). Product direction: architecture prepared to evolve into a multi-building SaaS without expanding the MVP beyond what the pilot needs.

What exists today

Backend (apps/api): identity/RBAC (Resident, Administrator), building/unit/membership, amenities and availability, shared/exclusive leisure and event reservations, server-authoritative pricing with historical snapshots, concurrency control (advisory locks, holds, expiration), Mercado Pago payments, cash payments, an append-only audit trail, and administrative operations (reservation/payment queries, cancel, reschedule, pricing, availability, event slots). Backend and full-stack validation are green in CI.
Client (apps/client): Angular + Ionic product client through Phase 5: authentication/session guards, resident amenity browsing, leisure/event reservation creation, Mercado Pago and cash payment flows, resident reservation history/detail, administrator dashboards/operations/configuration/audit/manual-review views, shared error handling and frontend hardening. See the completed MVP client backlog.
Cloud/DevOps: local Docker Compose + GitHub Actions CI are implemented. Phase 7 is deployed to Azure staging with production Dockerfiles, Terraform IaC, private PostgreSQL networking, managed-identity Blob Storage, persistent Data Protection keys, ACR, Container Apps, remote Terraform state and a manual OIDC-based deployment workflow. Apply builds/pushes versioned images, deploys revisions and validates the public client plus proxied API with smoke checks.
Business decisions (issue #2): building-operation policy is closed for MVP/pilot scope. See DEC-014 and DEC-015: pilot pricing (Event = ARS 5,000 flat inclusive of SUM/Pool/Barbecue, Leisure = free), Event time windows, no Shared Leisure capacity cap, the Event cancellation window, incident/damage reporting in place of a fixed fine schedule, Pool/Barbecue never independently bookable, Administrator-created resident onboarding, 24-hour pending-payment hold, and Administrator-only cash receipt confirmation. Decisions are applied as configuration/server-side policy, not client hardcoding. Full-day reservations (OQ-003) remain deferred, and the refund/financial consequence of a late/disallowed Event cancellation remains an explicit deferred follow-up rather than invented behavior.

Public staging demo

The Azure staging environment supports a deliberately limited one-click resident demo. When Demo:Enabled=true (staging only), startup seeds the deterministic pilot catalog plus a passwordless Demo Resident bound to unit 1A. POST /api/demo/session creates a non-persistent cookie session for that resident; the account is never granted Administrator.

The login UI discovers availability through GET /api/demo/status and exposes Open live demo only when the backend enables it. The deployment workflow also verifies the demo end to end: session creation, /api/auth/me, resident role/membership and an explicit 403 on the administrator authorization probe.

Goals

Replace informal/manual booking coordination with a clear availability calendar.
Support shared leisure bookings, exclusive leisure bookings and longer event slots.
Integrate online payments through Mercado Pago and controlled cash-payment confirmation.
Provide an administrator panel with traceability, history and configuration.
Keep source code and cloud operations under the product owner’s control.
Build the project with professional engineering practices: documentation-as-code, CI/CD, IaC, security, testing and FinOps.

Technology baseline

Area	Technology
Backend	C# / ASP.NET Core (.NET)
Client	Angular + Ionic + Capacitor
Database	PostgreSQL
Realtime	SignalR
Cloud	Microsoft Azure
Containers	Docker
IaC	Terraform
CI/CD	GitHub Actions
Configuration management	Puppet, only where host-level configuration is justified
Payments	Mercado Pago
Repository	Private GitHub monorepo

Repository layout

apps/
  api/
  client/
infrastructure/
  terraform/
  puppet/
docs/
  00-project/
  01-discovery/
  02-requirements/
  03-architecture/
  04-data/
  06-security/
  07-devops/
  09-finops/
  12-roadmap/
.github/
scripts/

Documentation

Branching

main is the stable integration branch. Work is performed in short-lived branches such as feat/*, fix/*, docs/*, infra/*, refactor/* and test/*. Changes should reach main through Pull Requests.

Source-code policy

This repository is private. End users and building administrators consume the hosted service; they do not receive repository, database or cloud-console access. Any future source-code transfer or licensing arrangement is a separate commercial/legal decision.