How avadatrum/hotel-pipa works
1. What this repo is
- A React + TypeScript single-page application built with Vite.
- It appears to be an internal operational dashboard for apartments, commissions/sales, documents, receipts, audit logs, and tide table data (“Tábua de Maré”).
- The app uses Firebase as its main backend.
2. Frontend application boundary
- The main client lives under src/.
- src/main.tsx bootstraps the app, while src/routes/index.tsx defines navigation structure.
- src/pages/ contains route-level screens, and src/components/ contains reusable UI and feature widgets.
- Styling is handled by Tailwind CSS plus src/styles/index.css.
3. Core backend/data platform
- Firebase is the architectural center:
- src/services/firebase.ts configures client access.
- firestore.rules and firestore.indexes.json define security and query support.
- firebase.json and .firebaserc wire the project to Firebase hosting/resources.
- There is also a Cloud Functions backend in functions/, suggesting server-side logic for privileged operations or integrations.
4. Server-side functions boundary
- functions/src/index.ts is the entry point for Firebase Cloud Functions.
- This layer likely handles trusted workflows that should not run in the browser, such as administrative actions, audit-sensitive updates, or Firestore triggers.
- The presence of functions/package.json and its own TypeScript config indicates it is deployed independently from the frontend.
5. Feature domains in the UI
- The app is organized by business domain rather than by technical layer:
- ApartmentsPage.tsx and apartment-related components/services.
- commissions/ pages, components, hooks, and utilities for commission management.
- TabuaDeMarePage.tsx and TabuaMareWidget.tsx for tide data.
- DocumentsPage.tsx, ReceiptsPage.tsx, AdminUsersPage.tsx, LogPage.tsx, and DashboardPage.tsx for operational/admin workflows.
- This suggests a dashboard with several tightly related internal modules.
6. State and cross-cutting contexts
- Global app state is managed with React contexts in src/contexts/:
- AuthContext.tsx for authentication/session state.
- CommissionContext.tsx for commission-related shared state.
- ThemeContext.tsx for UI theme handling.
- These contexts form the state layer that many pages and hooks consume.
7. Custom hooks as the main integration layer
- src/hooks/ contains the app’s primary data-access and behavior abstractions.
- Important examples:
- useAuth, usePermission, ProtectedRoute, AdminRoute for access control.
- useFirestore, useApartments, useApartmentActions, useTours, useTabuaMare for Firestore-backed domain data.
- useNavigation and useToast for UX flow.
- This indicates the app separates UI rendering from data-fetching/business interactions via hooks.
8. Service layer and business logic
- src/services/ contains the repository’s backend-facing business logic:
- authService.ts, commissionService.ts, apartmentService.ts, auditService.ts, tabuaMareService.ts, seedService.ts.
- These services are the main boundary between UI code and Firebase/Firestore.
- src/utils/commissionCalculations.ts holds domain calculations, likely used by commission dashboards and sales registration flows.
9. Commission module structure
- The src/components/commissions/ folder is a substantial subsystem with its own UI composition:
- dashboards, filters, tables, charts, forms, modals, rankings, and pagination.
- Corresponding pages in src/pages/commissions/ indicate this is a major product area:
- CommissionDashboard.tsx
- CommissionSettings.tsx
- CommissionsPage.tsx
- RegisterSalePage.tsx
- src/types/commission.types.ts supports this module’s data model.
10. Authentication and authorization flow
- User access is guarded at the routing/component level by ProtectedRoute.tsx and AdminRoute.tsx.
- AuthContext plus usePermission suggest role-based access control, likely tied to Firebase auth and Firestore user records.
- src/pages/LoginPage.tsx is the entry point for unauthenticated users.
11. Data seeding and operational scripts
- scripts/seedTours.ts and src/services/seedService.ts indicate seeded data workflows for commissions/tours.
- These scripts are separate from the runtime UI and are likely used during setup or test data population.
12. Public assets and app shell
- public/ and src/assets/ hold static resources.
- Shared shell components such as Layout.tsx, Footer.tsx, UserMenu.tsx, Toast.tsx, and Button.tsx compose the common UI frame around the routed pages.
13. Deployment and tooling
- The repo is set up for modern frontend build/deploy tooling:
- vite.config.ts for bundling.
- tailwind.config.js, postcss.config.js, and eslint.config.js for styling and code quality.
- vercel.json suggests frontend deployment on Vercel.
- Firebase deployment config suggests backend and/or hosting deployment through Firebase as well.
14. Architecture summary for diagramming
- The clean way to draw this repo is:
- Browser SPA at the center.
- Route pages on top.
- Shared contexts/hooks/services as the middle layer.
- Firebase Auth + Firestore as the primary data store and identity provider.
- Cloud Functions as the trusted server-side extension.
- Auxiliary scripts for seeding/admin tasks.
- The dominant boundary is between the React client and Firebase services, with commissions as the largest business subsystem.
Main entry points: index.tsx Routes · firebase.ts Firebase client · CommissionsPage.tsx Commissions · CommissionDashboard.tsx Commission dashboard
Components 30
Frontend shell
React entry, routing, layout, and access control around the SPA.
- App bootstrap · Bootstraps the client application.
src/main.tsx - Routes · Defines the SPA route structure and page boundaries.
src/routes/index.tsx - Layout · Shared page frame and navigation chrome.
src/components/Layout.tsx - Protected route · Blocks unauthenticated access to private areas.
src/components/ProtectedRoute.tsx - Admin route · Restricts admin-only screens and actions.
src/components/AdminRoute.tsx
Feature pages
Route-level screens for the main operational areas.
- Login · Entry point for unauthenticated users.
src/pages/LoginPage.tsx - Dashboard · Operational landing screen.
src/pages/DashboardPage.tsx - Apartments · Apartment management screen.
src/pages/ApartmentsPage.tsx - Documents · Document workflow screen.
src/pages/DocumentsPage.tsx - Receipts · Receipt and payment screen.
src/pages/ReceiptsPage.tsx - Users · Administrative user management screen.
src/pages/AdminUsersPage.tsx - Audit log · Audit and activity history screen.
src/pages/LogPage.tsx - Tide data · Tábua de Maré screen.
src/pages/TabuaDeMarePage.tsx
Commission domain
Commission-specific UI, state, and business flow.
- Commissions · Commission management entry page.
src/pages/commissions/CommissionsPage.tsx - Commission dashboard · Primary commission analytics and controls.
src/pages/commissions/CommissionDashboard.tsx - Commission settings · Configuration area for commission rules and preferences.
src/pages/commissions/CommissionSettings.tsx - Register sale · Sales registration flow for commissions.
src/pages/commissions/RegisterSalePage.tsx - Commission UI · Dashboards, tables, filters, charts, and forms for commission workflows.
src/components/commissions/CommissionCharts.tsx
Shared state
Contexts and hooks used across multiple screens.
- Auth state · Session and identity state for the app.
src/contexts/AuthContext.tsx - Commission state · Shared commission workflow state.
src/contexts/CommissionContext.tsx - Firestore hook · General Firestore access abstraction used by feature hooks.
src/hooks/useFirestore.ts - Permission hook · Role and access checks used by guarded screens.
src/hooks/usePermission.ts
Firebase backend
Firebase client, security rules, and server-side extensions.
- Commission service · Backend-facing commission logic and data access.
src/services/commissionService.ts - Apartment service · Apartment data access and updates.
src/services/apartmentService.ts - Audit service · Audit log persistence and retrieval.
src/services/auditService.ts - Tide service · Tábua de Maré data integration.
src/services/tabuaMareService.ts - Firebase client · Initializes the Firebase client used by services and hooks.
src/services/firebase.ts - Firestore rules · Server-enforced database access rules.
firestore.rules - Cloud functions · Firebase Functions entry point for trusted workflows.
functions/src/index.ts
Ops tooling
Scripts and deployment/build configuration supporting the app.
- Seed tours · Data seeding utility for tours/commission workflows.
scripts/seedTours.ts
Connections 42
- App bootstrap → Routes: boots · App startup hands off to routing.
- App bootstrap → Layout: mounts · App shell is mounted around routed content.
- App bootstrap → Auth state: provides · Global auth state is initialized at the top level.
- Routes → Login: routes to · Public entry screen.
- Routes → Dashboard: routes to · Default operational overview.
- Routes → Apartments: routes to · Apartment workflow screen.
- Routes → Documents: routes to · Document workflow screen.
- Routes → Receipts: routes to · Receipts workflow screen.
- Routes → Users: routes to · Admin-only user management.
- Routes → Audit log: routes to · Audit log screen.
- Routes → Tide data: routes to · Tide data screen.
- Routes → Commissions: routes to · Commission domain entry.
- Routes → Protected route: guards · Private screens are protected.
- Routes → Admin route: guards · Admin screens are role-checked.
- Protected route → Auth state: reads · Authentication state is required for private access.
- Admin route → Auth state: reads · Role checks depend on auth state.
- Admin route → Permission hook: checks · Permission logic backs admin gating.
- Layout → Dashboard: frames · Shared chrome wraps the dashboard and related screens.
- Layout → Apartments: frames · Shared chrome wraps domain pages.
- Commissions → Commission dashboard: shows · Main commission page surfaces the analytics dashboard.
- Commissions → Commission settings: links · Commission entry page exposes settings.
- Commissions → Register sale: links · Commission entry page exposes sale registration.
- Commission dashboard → Commission UI: composes · Dashboard is built from specialized commission widgets.
- Commission dashboard → Commission state: consumes · Shared commission state feeds the dashboard.
- Commission UI → Commission state: consumes · Widgets share commission state.
- Dashboard → Commission dashboard: links to · Dashboard exposes commission operations as a major area.
- Auth state → Firebase client: auths with · Authentication is backed by Firebase.
- Firestore hook → Firebase client: reads from · General Firestore access goes through the Firebase client.
- Commission service → Firebase client: uses · Commission data access is built on Firebase.
- Apartment service → Firebase client: uses · Apartment data access is built on Firebase.
- Audit service → Firebase client: uses · Audit persistence is built on Firebase.
- Tide service → Firebase client: uses · Tide data integration is built on Firebase.
- Commissions → Commission service: fetches · Commission UI depends on commission data operations.
- Commission dashboard → Commission service: fetches · Dashboard queries commission data.
- Register sale → Commission service: writes · Sale registration persists through commission services.
- Apartments → Apartment service: fetches · Apartment screen uses apartment data operations.
- Audit log → Audit service: fetches · Audit log screen uses audit data operations.
- Tide data → Tide service: fetches · Tide screen uses the tide service.
- Login → Auth state: updates · Login updates authentication state.
- Firestore rules → Firebase client: constrains · Client operations are governed by Firestore security rules.
- Cloud functions → Firestore rules: trusts · Cloud Functions operate alongside database security policy.
- Seed tours → Commission service: seeds · Seed script populates commission/tour-related data.