HotelMind AI

Stakeholders

Marked by whether the system as built actually serves them.

• Model-generated price changes require explicit human approval.

  Unsupervised AI pricing is the first thing a hotel buyer objects to, and the objection is legitimate - a bad automated rate change costs real revenue immediately and is hard to unwind.

  Alternatives considered

  • Fully automatic rate updates - the strongest demo and the weakest risk position
  • Automatic within a bounded band, escalating only outliers - viable later, but it needs a track record of accepted recommendations to set the band honestly

  Trade-off: Recommendations only create value when someone reviews them, so the system depends on an operator staying in the loop.

• Build the data warehouse before training any models.

  Models trained on ad-hoc extracts cannot be audited or reproduced later.

  Trade-off: Delayed the first visible ML feature by a significant margin.

• Event-driven delivery over Kafka rather than polling.

  Staleness is what makes an operator stop trusting a dashboard; push keeps the screen authoritative. Kafka also gave durable, replayable event history, which meant consumers could be added later without backfilling by hand.

  Alternatives considered

  • HTTP polling on an interval - simplest, but scales badly across twenty modules and leaves exactly the staleness that erodes trust
  • Postgres LISTEN/NOTIFY - no new infrastructure, but no durability or replay, and it couples every consumer to the database
  • Redis pub/sub alone - lightweight and already in the stack, but fire-and-forget with no retry or replay semantics

  Trade-off: Kafka and Zookeeper are substantial infrastructure for a single-property system. This is a real over-engineering risk, accepted for the durability guarantees and the learning - and worth naming rather than defending.

• PostgreSQL for both the operational schema and the warehouse.

  The hotel domain is strongly relational - hotel, branch, floor, room type, room, booking - and needs real constraints and transactions. Keeping the warehouse in the same engine avoided a second system to operate for a data volume that never warranted one.

  Alternatives considered

  • A dedicated warehouse engine such as BigQuery, Snowflake, or ClickHouse - better at scale, but adds cost and operational surface for a dataset this size
  • A document store for flexible booking shapes - loses the relational integrity the domain actually depends on

  Trade-off: Analytical queries compete with transactional load on the same engine, and the design would need revisiting well before multi-property scale.

• Hybrid retrieval - FAISS dense vectors plus BM25 - for the assistant.

  Operational questions mix semantics with exact terms. Dense vectors alone miss a specific room number or a rate code; keyword search alone misses paraphrasing. Combining them covers both failure modes.

  Alternatives considered

  • Dense vector search alone - simpler, but weak on exact identifiers and rare terms
  • Keyword search alone - precise but brittle to phrasing
  • A hosted vector database - less to operate, but adds cost and a dependency for a local-first project

  Trade-off: Two retrieval paths to tune and maintain, and hybrid scoring needs its own weighting decisions.

• Keep original component prop APIs during the Radix migration.

  Dozens of call sites already consumed those APIs; changing them would have turned a primitive upgrade into an app-wide rewrite.

  Trade-off: The components diverge from stock shadcn composition patterns, so upstream examples need translating.

• Open in light theme regardless of OS preference.

  The users are hotel managers, and a bright manager-oriented screen suits the context better than a dark analytics console.

  Trade-off: Users who prefer dark everywhere must opt in each time on a new device.

• Self-host the entire MLOps stack on Docker.

  A self-funded project cannot carry managed-service costs, and local-first keeps the design portable to Kubernetes or a cloud platform later without rework.

  Alternatives considered

  • Managed MLflow or a cloud ML platform (SageMaker, Vertex) - less to operate, but a recurring cost with no funding behind it
  • No MLOps layer, keeping flat pickle files - simplest, but leaves models unversioned and un-rollbackable

  Trade-off: No managed reliability - the platform inherits the single VM's failure modes.

• Publish the gap analysis, including the parts that score the work poorly.

  A reviewer doing diligence would find the synthetic training data and the label leakage anyway. Disclosing them first is both more useful and more credible.

  Trade-off: A casual reader may take the disclosed weaknesses as the headline rather than the capability behind them.

• The churn model's best-looking metric turned out to be label leakage, which meant discarding a result rather than shipping it.
• A server-overload incident forced LLM generation off in production, and exposed that the fallback path degraded silently.
• Two models had no real training data available, so they were trained on synthetic data and had to be labelled as directional rather than dependable.
• Maintaining consistency across roughly twenty feature modules as a single developer, which the small shared primitive layer exists to solve.
• Writing requirements after the fact for a system already built - useful, but the wrong order, and the analysis says so.

• Restaurant demand and staffing models are trained on synthetic data with no real-world validation.
• The churn model's accuracy is inflated by label leakage and the feature set needs rebuilding.
• Occupancy forecasting is validated against a relative baseline, not real room-inventory ground truth.
• The AI assistant's LLM generation is disabled in production and degrades to raw retrieval without telling the user.
• Review sentiment uses a keyword lexicon rather than a trained NLP model.
• Deployed on a single VM with no high availability and no rehearsed disaster recovery.
• JWT authentication only - no SSO, no MFA.
• No audit logging for sensitive actions such as refunds and rate overrides.
• Single-tenant: multi-branch is supported, unrelated hotel groups are not.
• No integration with any external PMS, POS, channel manager, or payment processor - it cannot take a booking or a payment end to end.
• No multi-property or portfolio-level reporting.
• GDPR, PCI DSS, and SOC 2 posture are entirely unaddressed.
• The BA document backlog is incomplete - PRD, BRD, personas, competitive analysis, and traceability matrix are unwritten.
• Accessibility has not been audited against WCAG.

• 01A metric that looks unusually good deserves suspicion before celebration. The churn accuracy was the best number in the project and the least real.
• 02Silent degradation is a product defect. If a system quietly stops doing the thing a user asked for, the interface has misled them regardless of how correct the fallback is.
• 03Requirements written after the build are useful documentation and poor analysis. The value came from what the exercise exposed, not from the artifact itself.
• 04Building the warehouse before the models felt like a detour and was the reason the ML work went quickly and stayed auditable.
• 05Choosing infrastructure for what it teaches is legitimate, but the cost should be stated plainly - Kafka for a single property is over-engineered, and pretending otherwise would be dishonest.
• 06Disclosing a weakness costs less than having it discovered. Writing the gap analysis was more valuable to the work than any feature added in the same period.

Product Management

Product scopingFeature prioritisationHuman-in-the-loop AI designRoadmap planningProduct positioning

Business Analysis

Requirements elicitationFunctional & non-functional requirementsAs-Is / To-Be process mappingGap analysisStakeholder analysisBusiness rulesAcceptance criteriaCompetitive benchmarking

Software Engineering

Next.jsReactTypeScriptFastAPIREST API designEvent-driven architectureWebSocketsPostgreSQLRedisApache KafkaDesign systemsTesting

Data Engineering

Dimensional modellingStar schema designApache AirflowdbtETL pipelinesIncremental loadingData lake (MinIO)

Machine Learning

XGBoostProphetRandom ForestRegressionTime-series forecastingFeature engineeringModel evaluationData-leakage diagnosis

Generative AI

RAGFAISSBM25Hybrid retrievalEmbeddingsChunking strategyLLM provider abstractionPrompt design

MLOps

MLflowModel registryPromotion & rollbackDrift detection (Evidently)PrometheusGrafanaScheduled retraining

Cloud & DevOps

DockerDocker ComposeNginx reverse proxyTLS / certbotcloud-init provisioningufw & fail2banBackup & restore scripting

Tools

GitGitHubNetlifyKafka UIMinIO Console