Next-Generation Multi-Tenant Estate Management SaaS Platform
- Ecosystem Components
- System Design (Architecture Overview)
- Shared Packages
- Interactive Model Flowchart & Architecture Visualizer
- Documentation & Markdown Tools
- Getting Started
- Testing
- Git Commit Rules & Automation
- GitHub Templates & Workflows
- Component Guides
- ⚙️ app/rezzident_BE: FastAPI Python Backend + fastguard (PostgreSQL Multi-Tenant Schema Isolation, Redis, Paystack Split Payments, JWT + PIN Auth).
- 💻 app/rezzident_FE: Modern TanStack Start (React + Vite + TailwindCSS) Web Portal (Community & Admin Management Dashboard).
- 📱 app/rezzident_MB: Expo / React Native Mobile Application (Community & Security Guard App).
┌─────────────────────────────────────────────────────────────────┐
│ SHARED API LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Web Client │ │ Mobile Client│ │ Admin Dashboard │ │
│ │ (Tanstack) │ │(React Native)│ │ (Web) │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Nginx / Traefik │ (TLS, rate limit) │
│ │ (Reverse Proxy + WAF) │ │
│ └────────────┬────────────┘ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ FastAPI + Fastgaurd │ │
│ │ api/v1/... │ │
│ │ + SaaS Subscription MW │ │
│ │ + slowapi Rate Limiter │ │
│ │ + Security Headers MW │ │
│ │ + OpenTelemetry │ │
│ └──────────┬──────────────┘ │
│ │ │
│ ┌──────────────┼──────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────┐ ┌────────────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Background Jobs │ │
│ │ │ │(Sessions │ │ ( ARQ ) │ │
│ │ │ │ + Cache) │ │ - Email │ │
│ │ │ │ │ │ - Subscription check│ │
│ └──────────────┘ └──────────┘ └────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Observability Stack │ │
│ │ Prometheus → Grafana | OTel → Jaeger | Loki (Logs) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
The monorepo shares code between FE and MB through workspace packages in /packages/:
| Package | Path | Consumed By | Purpose |
|---|---|---|---|
@rezzident/design-tokens |
packages/design-tokens/ |
FE + MB | Single source of truth for colors, typography, spacing, and border-radius. Both Tailwind configs import from here. |
@rezzident/shared-types |
packages/shared-types/ |
FE + MB + BE | TypeScript type definitions shared across all apps (auth, estate, user types). |
@rezzident/api-client |
packages/api-client/ |
FE + MB | Axios-based API client with React Query hooks (useAuth, useEstates, etc.). |
@rezzident/utils |
packages/utils/ |
FE + MB | Shared utility functions (formatters, validators, constants). |
- Each package is a standard npm package with its own
package.json(name scoped as@rezzident/*). - Apps reference them with
"@rezzident/design-tokens": "workspace:*"in theirpackage.json. - pnpm resolves
workspace:*to the local folder viapnpm-workspace.yaml. - No build step required — packages export raw
.tsfiles, and each app's bundler (Vite for FE, Metro for MB) compiles them at dev time.
packages/
├── design-tokens/ # colors, fontSize, spacing, borderRadius
│ ├── colors.ts
│ ├── typography.ts
│ ├── spacing.ts
│ └── index.ts # barrel re-export
├── shared-types/ # TypeScript interfaces
├── api-client/ # Axios + React Query hooks
└── utils/ # Shared helpers
To add a new token (e.g. a color), edit packages/design-tokens/colors.ts — both apps pick it up automatically on next dev server restart.
Rezzident features an automated interactive visual flowchart application for database models, foreign key connections, schema boundaries, and system workflows.
- Interactive Flowchart Application: models_interactive_flowchart.html
- Architectural Flowchart Report: models_and_system_flowchart_report.md
The interactive flowchart updates automatically whenever backend models are updated, added, or deleted:
-
Git Pre-Commit Hook: Any staged edit inside
apps/rezzident_BE/api/v1/models/*.pyautomatically triggers.git/hooks/pre-committo re-parse the SQLAlchemy AST and stage the updatedmodels_interactive_flowchart.html. -
FastAPI Development Startup: Starting the FastAPI server (
python main.py) in development mode auto-generates and refreshes the model graph. -
Manual Trigger: Contributors can manually regenerate the flowchart anytime by running:
python3 apps/rezzident_BE/scripts/generate_model_flowchart.py
Rezzident heavily uses Markdown (.md) for architecture decisions, guidelines, and project planning.
💡 Note: The
docs/architecturedirectory contains all core decisions, architectural guidelines, and execution plans for this project. These are living documents and will likely change over time as features evolve and plans adapt based on project requirements and feedback.
If you prefer to read the documentation without setting up a Markdown editor, you can access the live, auto-updating web viewer here: https://rezzident-ecosystem-ocx8.vercel.app
Depending on your role, here are the recommended tools to read and write documentation seamlessly locally:
- Visual Studio Code (VS Code): The standard IDE. We recommend installing the Markdown All in One and Prettier extensions for auto-formatting and table-of-contents generation.
- MarkdownLint: Enforces standard markdown formatting and prevents broken links.
- Obsidian: A powerful, visual Markdown editor that lets you view all documentation as an interconnected graph. It works directly with local folders (just open the
docs/orkickoff/folder as an Obsidian Vault). - Typora: A seamless, distraction-free WYSIWYG (What You See Is What You Get) Markdown editor. You don't need to look at raw syntax; it formats as you type. Highly recommended for non-developers.
The Rezzident ecosystem is a Turborepo monorepo using pnpm workspaces.
- Node.js ≥ 20
- pnpm ≥ 9 (
npm install -g pnpm) - Python ≥ 3.11 (for Backend)
- Docker (for infrastructure services: PostgreSQL, Redis)
Run this at the root of the project to install all dependencies for frontend, mobile, and shared packages:
pnpm installFor the backend (Python):
cd apps/rezzident_BE
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txtSpin up PostgreSQL, Redis, and observability services:
pnpm run infra:up
# Or directly: docker compose -f infrastructure/docker-compose.yml up -dTo spin up all apps concurrently using Turborepo:
pnpm run devThis starts:
- Backend (FastAPI) on
http://localhost:8000 - Frontend (Vite) on
http://localhost:3000 - Mobile (Expo) on
http://localhost:8082
If you want to work on a specific app without starting the others:
Backend (FastAPI):
cd apps/rezzident_BE && python main.pyFrontend (React/TanStack Start):
pnpm run dev:web
# OR: pnpm --filter rezzident-fe run devMobile (Expo React Native):
pnpm run dev:mobile
# OR: pnpm --filter rezzident-mb run devTo open the mobile app on a specific platform after starting:
- Press
i→ iOS Simulator - Press
a→ Android Emulator - Press
w→ Web browser - Scan QR code → Physical device (Expo Go)
Run every test suite across the entire monorepo in one command:
pnpm test:allThis runs, in order:
- Frontend tests (Vitest)
- Mobile tests (Jest)
- Backend tests (pytest)
- Shared package tests (Vitest)
Frontend (rezzident_FE) — Vitest + Testing Library:
pnpm test:fe
# Or directly:
cd apps/rezzident_FE && pnpm test
# Watch mode (re-runs on file changes):
cd apps/rezzident_FE && npx vitestMobile (rezzident_MB) — Jest + Testing Library RN:
pnpm test:mb
# Or directly:
cd apps/rezzident_MB && pnpm test
# Watch mode:
cd apps/rezzident_MB && npx jest --watchBackend (rezzident_BE) — pytest:
pnpm test:be
# Or directly:
cd apps/rezzident_BE && source venv/bin/activate && python3 -m pytest tests/ -v
# Run a single test file:
cd apps/rezzident_BE && python3 -m pytest tests/test_auth.py -v
# Run with coverage:
cd apps/rezzident_BE && python3 -m pytest tests/ --cov=api --cov-report=term-missing@rezzident/utils (validators, formatters):
pnpm --filter @rezzident/utils test
# Or directly:
cd packages/utils && npx vitest run| App / Package | Framework | Command | Test Files |
|---|---|---|---|
| rezzident_FE | Vitest + Testing Library | pnpm test:fe |
src/**/*.test.{ts,tsx} |
| rezzident_MB | Jest + Testing Library RN | pnpm test:mb |
__tests__/**/*.test.ts |
| rezzident_BE | pytest | pnpm test:be |
tests/test_*.py |
| @rezzident/utils | Vitest | pnpm --filter @rezzident/utils test |
*.test.ts |
| All | — | pnpm test:all |
Everything above |
While formatting and linting happen automatically on pre-commit, you can manually run the checks and auto-fix issues.
Both the web frontend and mobile app use ESLint and Prettier.
To run checks from the project root using Turborepo:
pnpm turbo run lint --filter=rezzident-fe
pnpm turbo run lint --filter=rezzident-mbTo auto-fix errors: Navigate to the specific app directory and run the fix commands:
# For Frontend
cd apps/rezzident_FE
pnpm run lint --fix
pnpm run format
# For Mobile
cd apps/rezzident_MB
pnpm run lint --fix
pnpm run formatThe backend is excluded from the monorepo tooling. It uses Ruff for linting and Black for formatting. You must run these commands inside the backend directory with the virtual environment active.
cd apps/rezzident_BE
source venv/bin/activate
# 1. Check for formatting and linting errors
ruff check . && black --check .
# 2. Auto-fix all possible errors and format the code
ruff check --fix --unsafe-fixes . && black .We strictly follow the Conventional Commits specification for our commit messages. This ensures a readable Git history and enables automated changelog generation.
To keep our repository organized, we enforce strict branch naming conventions that mirror our commit types:
type/kebab-case-description
feat/: New features (e.g.,feat/auth-otp-screen)fix/: Bug fixes (e.g.,fix/phone-validation-bug)chore/: Tooling, dependencies, and configuration (e.g.,chore/add-eslint-mb)refactor/: Code restructuring (e.g.,refactor/extract-auth-hook)docs/: Documentation updates (e.g.,docs/api-readme)test/: Adding or modifying tests (e.g.,test/auth-middleware)perf/: Performance optimizations (e.g.,perf/optimize-queries)style/: Formatting changes (e.g.,style/format-json)ci/: CI/CD pipeline changes (e.g.,ci/fix-lint-workflow)
All branches should be created off of the develop branch.
<type>(<scope>): <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Optional. The area of the code (e.g., auth, billing, ui).
│
└─⫸ The type of change (see below).
Allowed Types:
feat: A new feature (correlates with a MINOR version bump).fix: A bug fix (correlates with a PATCH version bump).docs: Documentation only changes.style: Changes that do not affect the meaning of the code (white-space, formatting, etc).refactor: A code change that neither fixes a bug nor adds a feature.perf: A code change that improves performance.test: Adding missing tests or correcting existing tests.build: Changes that affect the build system or external dependencies (example scopes: vite, pnpm).ci: Changes to our CI configuration files and scripts.chore: Other changes that don't modifysrcor test files.
Examples:
feat(auth): implement phone verificationfix(billing): correct invoice calculation errordocs: update API setup instructions
To ensure code quality and prevent formatting arguments, we use Husky and lint-staged to automatically lint and format your code before it gets committed.
When you run git commit, the following happens automatically:
- Formatting:
prettierruns on all staged files (.ts,.tsx,.json,.md), ensuring consistent spacing and automatically sorting Tailwind CSS classes. - Linting:
eslint --fixruns on staged frontend/mobile TypeScript files, fixing minor issues and enforcing architecture boundaries (e.g., Feature-Sliced Design).
Bypassing Hooks (Emergency Only): If you need to save a broken WIP commit, you can bypass the hooks using:
git commit -m "chore: wip broken state" --no-verify(Note: Code bypassing these hooks will still fail the CI/CD pipeline on GitHub).
The .github/ directory contains templates and CI/CD workflows that enforce contribution standards.
Create structured issues directly from GitHub's Issues → New Issue page. Available templates:
| Template | File | Use For |
|---|---|---|
| Bug Report | .github/ISSUE_TEMPLATE/bug-report.md |
Production/staging bugs with reproduction steps |
| Design Issue | .github/ISSUE_TEMPLATE/design.md |
UI/UX design tasks and Figma references |
| Engineering (Backend) | .github/ISSUE_TEMPLATE/engineering-backend.md |
API endpoints, models, migrations |
| Engineering (Frontend) | .github/ISSUE_TEMPLATE/engineering-frontend.md |
Web/mobile UI features, components |
How to use: Go to your repo on GitHub → Issues → New Issue → Select a template from the list. Fill in the pre-populated sections.
PRs use role-specific templates. Append the template name to the PR URL:
| Template | URL Parameter | Use For |
|---|---|---|
| Default | (auto-selected) | General PRs |
| Backend | ?template=backend.md |
API/model changes |
| Frontend | ?template=frontend.md |
Web UI changes |
| Mobile | ?template=mobile.md |
Mobile app changes |
How to use: When creating a PR, add the template query parameter to the URL:
https://github.com/<org>/rezzidentEcosystem/compare/main...your-branch?quick_pull=1&template=backend.md
Or navigate to the PR creation page and replace the default template content with the one from .github/PULL_REQUEST_TEMPLATE/<name>.md.
.github/CODEOWNERS automatically assigns reviewers based on which files are changed:
| Path | Required Reviewers |
|---|---|
apps/rezzident_BE/ |
@backend-team |
apps/rezzident_FE/ |
@frontend-team |
apps/rezzident_MB/ |
@mobile-team |
packages/shared-types/ |
@backend-team + @frontend-team |
packages/api-client/ |
@frontend-team + @mobile-team |
packages/design-tokens/ |
@frontend-team + @mobile-team |
Workflows in .github/workflows/ run automatically on push/PR events. Check the workflow files for specific triggers and jobs.
Check out the detailed guides in each component directory for deeper development flows: