The request
Architecture overview of holiday-home management web app
Read the full request
Read this repository, a web application that a small company uses to manage holiday-home care contracts and short-term rentals, and answer in text with an architecture overview for a developer joining the project: the technology stack, how the code is organised into layers (pages, domain modules, database, shared helpers), the main business modules and what each one does, the user roles and what each can see, and how the test suite is organised. Do not change, add or delete any file: the deliverable is the written answer only. Keep the answer anonymous: refer to the company only as "the operator", and do not name the company, any person, property, address, domain name, email address or file name that contains the company's name.
The journey
- Read the requestTurned it into a list of things it would have to prove before calling the work done.
- Did the workPlanned the pieces, built them and checked the result as it went.
- DeliveredThe answer is written below.
The result
Architecture overview
Stack
- TypeScript with strict compiler settings, React 19, and Next.js App Router.
- Node.js server runtime with SQLite via
node:sqlite; JSON provides catalogue seed data. - Vitest runs the tests in a Node environment, with V8 coverage configured.
- Server-side integrations include email, calendar feeds, uploads, push notifications, and QR-code generation.
Code organisation
- Pages and delivery:
src/app/contains App Router pages, layouts, API routes, server actions, authentication flows, and route-specific UI.src/components/contains reusable presentation components. Middleware preserves the requested path for authentication redirects. - Domain layer:
src/domain/contains business rules independent of page rendering and persistence. Modules cover properties, care contracts, rental calculations, checklists, users, guests, guides, operations, maintenance, repairs, logistics, supplies, onboarding, communications, documents, alerts, and testimonies. - Database layer:
src/db/owns SQLite connection/migrations, schema, seed data, repositories, and persistence services for users, sessions, properties, bookings, operations, contracts, reports, mail, and supporting records.src/lib/db.tsinitialises and seeds the database on first use. - Server helpers:
src/lib/adapts authentication, database access, mail, calendar synchronisation, uploads, redirects, reminders, and other server concerns. - Shared helpers:
src/shared/provides UTC ISO-date operations, euro amounts represented as integer cents, and relative-time formatting.
Main business modules
- Properties/catalogue: managed-home records, photos, capacities, service lines, listings, calendar feeds, and owner assignment.
- Care: annual care subscriptions, legacy contract terms, payment schedules, renewals, cancellations, balances, refunds, and printable contracts.
- Rental: bookings, channel fees, occupancy, seasonal rules, statements, rental history, stay reminders, and turnover checklists.
- Operations and field work: planned work, maintenance visits, cleaning, repairs, check-in/out, visit reports, photos, validation, and offline field submission.
- Checklists: Home Watch templates, visit checklists, findings, and report validation.
- Maintenance, repairs, logistics, and supplies: recurring plans, repair proposals/history, task coordination, stock and consumables.
- Guests and guides: guest details, evaluations, house guides, access-code timing, emergency information, and local recommendations.
- Communications: conversations, broadcasts/messages, email delivery/outbox, notifications, and report distribution.
- Onboarding and administration: owner-submitted homes, approval into the catalogue, accounts, roles, settings, documents, alerts, costs, accounting, statements, and testimonials.
Roles and visibility
- Admin: unrestricted operational and financial visibility; manages users, settings, contracts, property links, approvals, alerts, and report validation; can plan, complete, and cancel operations.
- Host: sees only their own approved properties and related bookings, maintenance, operations, rental/care information, statements, and costs; can submit a home for onboarding and manage their own account.
- Operator: sees all properties and bookings but not financial amounts; plans and completes operational work, including maintenance, repairs, cleaning, check-in/out, logistics, supplies, and field reports. Submitted reports require admin validation before becoming final owner-facing reports.
- Guest: sees only their own stay, stay details, conversations/messages, and the relevant house guide. Access codes are time-limited around the stay.
Tests
- Tests are standalone TypeScript files under
test/, generally organised one suite per business or infrastructure module: bookings, care, rental, checklists, properties, users/sign-in, database, mail, calendar synchronisation, operations, repairs, supplies, guides, onboarding, statements, reminders, and related cross-cutting behavior. - Vitest includes
test/**/*.test.ts, uses the Node environment, and has a 20-second timeout because database setup performs password hashing. - Database-oriented suites create in-memory SQLite databases, run migrations/seeding, exercise repository/domain workflows, and assert visibility, validation, lifecycle, and persistence behavior. Pure domain and shared-helper suites test deterministic calculations and validation rules directly.
- Coverage is configured with the V8 provider over
src/**.