Alojamento Ideal

Alojamento Ideal is a full rebuild of a production booking platform for a short-term rental operator managing apartments along Portugal's North Coast, together with local tours and activities.

The rewrite was more than a visual refresh. I used it as an opportunity to rethink the platform's architecture, separate shared concerns into reusable packages, introduce a caching layer for expensive catalog and availability flows, and make the booking experience more resilient across several external services.

The result is a modern monorepo that brings the guest-facing website, operator admin panel, transactional emails, database layer, authentication, shared UI, and business logic into one coherent system.

The Product

Alojamento Ideal is designed around two connected experiences.

For guests, the platform provides:

• Search and browsing for apartments with availability, pricing, and interactive maps
• Discovery and booking of local activities and tours
• A shared cart and checkout that can combine accommodation and activities
• User accounts with booking history, bookmarks, reviews, and identity verification
• Direct messaging, help content, and contact forms
• Order pages with live reservation details, editable trip information, and downloadable tickets

For the operator, it provides an administrative workspace for:

• Reservations, orders, refunds, and payout accounts
• Guest conversations through a unified inbox
• Property and owner-facing performance views
• Support content and help articles
• Operational workflows that need to remain synchronized with the underlying property-management systems

This makes the platform considerably more complex than a typical marketing website or CRUD dashboard: it is a customer-facing commerce system connected to several external sources of truth.

Rebuilding the Architecture

The rewrite is organized as a Bun workspace monorepo managed with Turborepo. Instead of allowing each application to develop its own versions of core logic, shared concerns live in dedicated packages and are consumed by the web and admin applications.

apps/
  web/      Guest-facing website, account, cart, and checkout
  admin/    Operator panel for reservations, payouts, inbox, and support
  emails/   Transactional email templates
packages/
  core/     Business logic, integrations, and cross-cutting concerns
  db/       PostgreSQL schema and migrations
  auth/     Authentication and session configuration
  ui/       Shared component library
docs/       Architecture notes and integration research

This structure gives the project clearer boundaries between presentation, domain logic, infrastructure, and shared functionality. It also makes it possible to evolve the guest and admin experiences without duplicating contracts or business rules.

The stack is built around Next.js 16, TypeScript, Bun, Turborepo, Biome, PostgreSQL, and Drizzle ORM, with shared packages providing consistent types, UI primitives, authentication, and domain functionality across the repository.

Caching as a First-Class Concern

A booking platform needs both speed and accurate live data. Static catalog information can be cached aggressively, while availability, quotes, and reservation state must still be checked against the relevant provider at the correct moment.

The rewrite introduces a dedicated caching approach for catalog data and cache-aware rendering, including Next.js cache components and reusable catalog cache helpers. This reduces unnecessary calls to external providers and improves the experience of browsing properties, while preserving live checks for the parts of a booking that cannot safely rely on stale data.

The result is a deliberate separation between:

• Cached, normalized catalog content used for fast browsing
• Live availability and pricing queries used during booking
• Reservation and payment state that must be reconciled reliably

This distinction is essential for keeping the website responsive without treating time-sensitive booking data as ordinary page content.

External Integrations

The platform coordinates several external services, each with its own API conventions and failure modes:

• Hostify provides property-management data, calendars, availability, pricing, and reservation operations.
• Stripe handles payments, split payouts through Stripe Connect, refunds, and webhook-driven reconciliation.
• Bokun powers the activities catalog, availability, and activity bookings.
• Hostkit supplies fiscal and reservation data needed by the operator.
• Pusher supports real-time messaging and updates.
• Resend is used for authentication and transactional email delivery.

Provider-specific behavior is kept behind typed integration clients and internal contracts. Raw external responses are transformed into application-owned representations so the rest of the system does not need to understand every provider's schema, authentication mechanism, or error format.

Booking and Payment Reliability

The most demanding part of the system is the booking path. A reservation may involve inventory holds, live quoting, payment authorization, provider confirmation, webhooks, and background reconciliation.

The platform follows a reserve-first flow for accommodation bookings: inventory is held before payment, then confirmed or released depending on the outcome. This helps prevent double bookings when requests overlap or when a downstream step fails.

The system is designed around failure rather than assuming every operation succeeds:

• Holds are verified before payment capture
• Provider reservations can be reconciled after payment
• Webhooks are processed idempotently
• Refunds are reconciled when confirmation cannot be completed
• Partial failures are represented explicitly instead of being hidden behind a generic success state

This turns the booking flow into a controlled distributed transaction across systems that the application does not own.

Admin and Operational Tooling

The admin application is not an afterthought. It gives the operator visibility into the state of reservations, orders, refunds, payouts, guest communication, and support content.

The internal tools are designed around safe operational workflows: administrators need to understand what happened, what is pending, and which external system requires attention. This means surfacing provider state, protecting sensitive actions with server-side authorization, and making reconciliation and support work possible without direct database access.

Building both sides of the product also made it possible to treat the guest experience and the operational experience as one system rather than two disconnected applications.

Technology

Why This Rewrite Matters

The original platform proved the business model and the integration requirements. The rewrite focuses on giving those requirements a stronger foundation.

It improves the project in several important ways:

• A monorepo keeps shared code, contracts, and tooling consistent
• Clearer package boundaries make the system easier to maintain
• Caching reduces unnecessary external API calls and improves browsing performance
• Typed adapters isolate provider-specific complexity
• A PostgreSQL-based data layer provides a stronger foundation for transactional workflows
• Separate web, admin, and email applications reflect the actual product boundaries
• Resilient booking and payment flows account for partial failures from the beginning

Alojamento Ideal is a project about engineering beyond the page: building a reliable product around real users, real payments, live inventory, and external systems that can fail independently.

Final Reflection

This rewrite represents a significant step forward from the first version of Alojamento Ideal. It gave me the opportunity to revisit decisions made during the initial build and apply what I had learned about integration-heavy systems, caching, monorepo design, operational tooling, and distributed workflows.

The result is not simply a newer frontend. It is a more deliberate platform: faster where it can be, live where it must be, and structured to support the hospitality business as its booking, activity, and operational needs continue to grow.