How iphonegalaxy/acerto-de-contas works
1. High-level shape
- This repository is a client-side single-page web app for shared expense tracking.
- There is no separate backend in the repo; the app relies on Firebase for authentication and data persistence, and is deployed as a static site on GitHub Pages.
2. Primary application surface
- index.html is the core application entry point and, per the README, contains the full React + Firebase app.
- The rest of the repo mostly supports that app: configuration, security rules, PWA assets, deployment, and smoke tests.
3. Identity and session boundary
- Users authenticate through Firebase Authentication using Google or email/password.
- Anonymous auth is explicitly not used.
- Each user account is later linked to a single household/family context, which is the main tenancy boundary for the app.
4. Multi-tenant data model
- The app is organized around a householdId that isolates one couple/family’s data from another.
- Access is membership-based: data visibility is governed by whether the signed-in user belongs to that household.
- The README also makes clear that a user can belong to one family at a time, and the family creator can delete the family and all associated data.
5. Realtime data layer
- The app uses Firestore as the live datastore, which gives real-time synchronization between devices.
- This is the main source of truth for shared financial records, so changes made by one person appear immediately to the other.
- Firestore is also where the app stores household-scoped entities such as members, cards, transactions, and related monthly history.
6. Core business rules
- The business logic is not generic splitting; it has fixed rules:
- Pessoa 1 pays 100% of card bills in payment calculations.
- Pessoa 2 has exclusive access to the Ajuste type.
- Cards marked Ambos are split half-and-half in totals.
- Dividido means 50/50.
- These rules are part of the domain layer inside the client app and affect how totals and obligations are computed.
7. Statement import pipeline
- A major workflow is importing credit-card statements from bank files.
- The user selects a bank and uploads CSV or XLSX files; the app detects cards from the statement and persists them into the household.
- The README currently highlights C6 Bank as supported, with other banks listed as future support.
- This import path is a separate ingestion flow from manual entry, but both end up writing into the same Firestore-backed household data.
8. Monthly navigation and card views
- The UI supports monthly history browsing, so the app is not just a current-state dashboard; it can reconstruct and navigate prior months.
- There is also a bank filter in the card tab, which indicates the UI can slice the household’s card data by institution or show all cards.
9. PWA/browser layer
- The app is packaged as a PWA using manifest.json and sw.js.
- That means the browser layer provides installability and some offline-capable shell behavior, even though the shared data still depends on Firebase connectivity for realtime sync.
- .nojekyll is present to make GitHub Pages serve the site without Jekyll processing.
10. Configuration and deployment
- firebase-config.example.js is the local template for Firebase client configuration; the real config is expected to be injected/created from environment or secrets.
- .github/workflows/pages.yml handles automated deployment to GitHub Pages when main changes.
- The README indicates Firebase credentials are supplied as GitHub Secrets, so the deployed site is static but configured at build time to talk to the correct Firebase project.
11. Security boundary
- firestore.rules is a key architectural file because it enforces the tenant boundary in Firestore.
- The app’s security model depends on Firestore rules matching the application’s household membership model, preventing cross-family reads/writes even though all users share the same backend project.
12. Verification and operational checks
- docs/smoke/ contains smoke-test scripts, including a family-join flow and a generic post-deploy check.
- This suggests the repo treats deploy-time verification as part of the architecture: after publishing to Pages, the app is validated against the live environment and Firebase-backed flows.
13. Mental model for a diagram
- The cleanest diagram is: browser/PWA client in the center, with arrows to Firebase Auth for login, Firestore for shared household data, GitHub Pages for static hosting, and file import sources for statement ingestion.
- The most important internal boundary is the household/family tenant boundary, enforced both in app logic and in Firestore rules.
Main entry points: index.html App entry · run-smoke.mjs Smoke checks · manifest.json Browser shell · pages.yml GitHub Pages
Components 18
Client App
Browser-based single-page app and domain logic
- App entry · Single-page app bootstrap and main UI surface
index.html - Sign-in · Firebase Authentication using Google or email/password
index.html - Household · Single-family context centered on householdId and membership
index.html - Expense ledger · Shared members, cards, transactions, and monthly history
index.html - Split rules · Pessoa 1, Pessoa 2, Ambos, and Dividido payment logic
index.html - Statement import · Bank statement upload and card detection from CSV/XLSX files
index.html - Monthly views · Browse prior months and reconstruct household history
index.html - Bank filter · Slices card views by institution or shows all cards
index.html - Bank files · CSV and XLSX statement uploads from supported banks
Firebase
Authentication, realtime datastore, and security boundary
- Auth service · Identity provider for signed-in users
- Firestore · Realtime household-scoped source of truth
- Firestore rules · Enforces household membership and tenant isolation
firestore.rules
Delivery
Static hosting and PWA packaging
- Browser shell · Installable static client shell
manifest.json - Service worker · Service worker for offline-capable shell behavior
sw.js - GitHub Pages · Automated deployment target for the published site
.github/workflows/pages.yml - Firebase config · Template for injected Firebase project settings
firebase-config.example.js - Secrets · Build-time Firebase credentials supplied to deployment
.github/workflows/pages.yml
Verification
Deployment checks and smoke tests
- Smoke checks · Family-join and live post-deploy verification scripts
docs/smoke/run-smoke.mjs
Connections 21
- Browser shell → App entry: hosts UI · The browser loads the static SPA shell
- Service worker → Browser shell: caches · Service worker supports offline-capable shell behavior
- GitHub Pages → Browser shell: deploys · GitHub Pages serves the static site
- Secrets → GitHub Pages: configures · Deployment injects Firebase credentials at build time
- Firebase config → App entry: initializes · Client config connects the app to the chosen Firebase project
- App entry → Sign-in: sign in · Users authenticate before accessing household data
- Sign-in → Auth service: verify identity · Firebase Authentication handles user sign-in
- App entry → Household: bind session · App binds the session to a single household context
- Household → Expense ledger: scope · All shared expense data is household-scoped
- Household → Split rules: govern · Tenant-aware business rules shape obligations and balances
- Split rules → Expense ledger: apply splits · Calculated obligations and allocations are written into shared data
- App entry → Expense ledger: read/write · Realtime shared data is stored in Firestore
- Expense ledger → Monthly views: browse months · Past periods are reconstructed from stored monthly state
- Expense ledger → Bank filter: filter cards · Card views can be sliced by institution
- App entry → Statement import: import statements · Users ingest bank statements into the shared ledger
- Statement import → Bank files: upload · CSV/XLSX statement files are the input source
- Expense ledger → Firestore: persist · Household data lives in Firestore
- Firestore → Firestore rules: protected by · Rules gate reads and writes by household membership
- Smoke checks → GitHub Pages: validates · Post-deploy checks exercise the live published app
- Smoke checks → Auth service: join flow · Smoke tests cover authentication and family join
- Smoke checks → Firestore: live check · Smoke tests verify Firebase-backed behavior