🏦 Family Office

A full-stack, production-grade family wealth management platform — real-time analytics, AI financial advice, and collaborative multi-member budgeting.

Live App · API · API Docs · Report Bug · Request Feature

About

Family Office is a household finance platform built for families who want the visibility of a proper wealth-management tool without the enterprise price tag. Multiple family members can share one workspace with role-based permissions, track income and expenses, plan budgets, chase savings goals, and get AI-generated financial advice — all from a single dashboard.

It's built the way a real product would be: async FastAPI backend, typed React frontend, containerized services, CI/CD on every push, and a clean layered architecture (routes → services → repositories → models) that's easy for new contributors to navigate.

Screenshots

Landing Page	Dashboard	AI Advisor
Clean marketing page with feature highlights	Real-time income/expense analytics	Multi-turn financial chatbot

Add screenshots or a short demo GIF to docs/assets/ and link them here — it's the single biggest thing that makes a README feel alive to a new visitor.

Features

💰 Core Financial Management

Multi-member family accounts with role-based permissions (admin, member, dependent, advisor)
Full CRUD transaction management with filtering and pagination
Income tracking with recurring source management and trend analytics
Expense analytics with category breakdown and month-over-month comparisons
Interactive budget planning with real-time budget-vs-actual tracking
Savings goals with progress tracking, contributions, and deadline projections

👪 Family Workspace

Guided family setup — new users name or join a family on first login (no silent auto-creation)
Invite members by email with assigned roles directly from Settings
GET /families/me returns every family a user belongs to, across devices
Admins can remove members from the workspace at any time

🤖 AI & Analytics

Conversational AI financial advisor with live financial context injection (Google Gemini)
Spending anomaly detection via Isolation Forest
Expense forecasting via Linear Regression, projecting 1–12 months ahead
Composite 0–100 financial health score (savings rate, liquidity, trend)
Rule-based quick insights alongside deeper AI-generated analysis
Receipt OCR upload via EasyOCR

🔒 Security

JWT authentication with bcrypt password hashing
Granular per-family, per-member permission flags
Rate limiting (60 req/min general, 10 req/min on auth endpoints)
CORS locked to the production frontend origin
Soft deletes throughout — no data is ever hard-destroyed
Full request validation via Pydantic v2

🎨 UI/UX

Full dark mode via CSS variables and a data-theme attribute
Guided onboarding flow for new users
Responsive layout for desktop and mobile
PDF/Excel report export

Tech Stack

Backend


FastAPI 0.115	Async Python web framework
PostgreSQL 16	Primary database (async via `asyncpg`)
SQLAlchemy 2.0	Async ORM with declarative models
Alembic	Schema migrations
Redis + Celery	Background jobs & task queue
Pydantic v2	Request/response validation
Google Gemini	AI financial advisor & summaries
scikit-learn	Isolation Forest anomaly detection
Pandas / NumPy	Analytics & forecasting
EasyOCR	Receipt image text extraction
ReportLab / openpyxl	PDF & Excel report generation

Frontend


React 18 + TypeScript	Component-based UI
Vite 5	Build tooling & dev server
React Router v6	Client-side routing
Recharts	Data visualization
Lucide React	Icon library

Infrastructure


Docker / Docker Compose	Local & containerized services
Nginx	Reverse proxy (containerized deploy)
GitHub Actions	CI/CD — lint, test, build, deploy
Render	Backend + managed PostgreSQL
Vercel	Frontend hosting

Architecture

The backend follows a layered design so business logic stays independent of both the web framework and the database:

Route (api/routes) → Service (services) → Repository (repositories) → Model (models)

Routes handle HTTP concerns only — parsing, auth, response shaping
Services hold business logic (permissions, scoring, forecasting, AI orchestration)
Repositories are the only layer that talks to the database
Models are plain SQLAlchemy ORM classes

See docs/SYSTEM_DESIGN.md and docs/AI_ARCHITECTURE.md for the full breakdown, and docs/DATABASE_SCHEMA.md for the data model.

Project Structure

Family-office/
│
├── backend/                        # FastAPI application
│   ├── app/
│   │   ├── main.py                 # App factory, CORS, lifespan (runs init_db on startup)
│   │   ├── config.py                # Pydantic settings (env vars)
│   │   ├── dependencies.py          # FastAPI dependency injection
│   │   │
│   │   ├── api/routes/              # auth, families, transactions, analytics,
│   │   │                            # ai, savings, budgets, reports, notifications, uploads
│   │   ├── core/                    # security, permissions, middleware, rate limiter, logging
│   │   ├── database/                # engine/session, init_db, Alembic migrations
│   │   ├── models/                  # 12 SQLAlchemy ORM models
│   │   ├── schemas/                 # Pydantic request/response schemas
│   │   ├── repositories/            # Database access layer
│   │   └── services/                # Business logic layer
│   │
│   ├── Dockerfile
│   ├── requirements.txt
│   └── alembic.ini
│
├── frontend/                        # React + Vite application
│   ├── src/
│   │   ├── App.tsx                  # Router + ProtectedLayout + family-setup guard
│   │   ├── context/                 # AuthContext, ThemeContext
│   │   ├── services/api.ts          # All API calls
│   │   ├── pages/                   # Landing, Login, Register, FamilySetup, Dashboard,
│   │   │                            # Transactions, SavingsGoals, BudgetPlanning,
│   │   │                            # AIAdvisor, Settings, Reports
│   │   └── styles/globals.css       # CSS variables incl. dark mode theme
│   │
│   ├── vercel.json                  # SPA rewrite rules for Vercel
│   └── package.json
│
├── docker/                          # Nginx / backend / frontend container configs
├── scripts/                         # deploy.sh, setup_dev.sh, init_db.sql
├── docs/                            # API, schema, deployment, AI & system design docs
├── .github/
│   ├── workflows/                   # ci-cd.yml, pr-check.yml
│   └── ISSUE_TEMPLATE/              # bug_report.md, feature_request.md
├── docker-compose.yml
├── Makefile
└── README.md

Getting Started

Prerequisites

Docker Engine 24+ and Docker Compose v2
Node.js 20+
Python 3.12+

1. Clone and configure

git clone https://github.com/kashish334/Family-office.git
cd Family-office

cp .env.example .env
# Edit .env with your own secrets and API keys

2. Run everything with Docker (recommended)

make setup   # first-time setup
make up      # start db, redis, api, celery, frontend, nginx

Or run services manually:

2b. Backend only

cd backend
pip install -r requirements.txt

docker compose up db redis -d   # start dependencies

uvicorn app.main:app --reload   # tables auto-created on startup via init_db

2c. Frontend only

cd frontend
npm install

echo "VITE_API_URL=http://localhost:8000" > .env.local
npm run dev

3. Access the application

Service	URL
Frontend	http://localhost:5173
API	http://localhost:8000
Interactive API Docs	http://localhost:8000/docs

Environment Variables

Backend

Variable	Description
`ENVIRONMENT`	`production` or `development`
`SECRET_KEY`	Random secret used for token signing
`JWT_SECRET_KEY`	Random secret used for JWT signing
`POSTGRES_HOST` / `PORT` / `DB` / `USER` / `PASSWORD`	Database connection
`DATABASE_URL`	Async connection string (`postgresql+asyncpg://...`)
`REDIS_URL`	Redis connection for caching/queues
`CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND`	Background task queue
`ALLOWED_ORIGINS`	Comma-separated list of allowed frontend origins
`GEMINI_API_KEY`	Google Gemini key for AI features
`OPENAI_API_KEY` / `OPENAI_MODEL`	Optional alternate AI provider

Full list with defaults: .env.example

Frontend

Variable	Description
`VITE_API_URL`	Backend base URL, e.g. `https://your-api.onrender.com`

Useful Make Commands

make up            # start all services
make down           # stop all services
make logs            # tail logs for all services
make dev-api          # run backend in dev mode
make dev-frontend      # run frontend in dev mode
make migrate            # apply Alembic migrations
make migrate-new         # generate a new migration
make seed                 # seed sample data
make test                  # run backend test suite
make test-cov                # run tests with coverage
make lint                     # lint backend + frontend
make format                    # auto-format code

Run make help for the full list.

Deployment

Backend → Render

Push the repo to GitHub
Render → New → Web Service → connect the repo
Runtime: Docker · Dockerfile Path: backend/Dockerfile · Build Context: backend
Add the backend environment variables listed above
Tables are auto-created on startup via init_db() — no manual migration step required for a fresh deploy

Frontend → Vercel

Vercel → New Project → import the repo
Root Directory: frontend
Add VITE_API_URL pointing at your deployed backend
Deploy — vercel.json handles SPA routing automatically

Full walkthrough: docs/DEPLOYMENT_GUIDE.md

API Reference

Full reference: docs/API_DOCUMENTATION.md · Interactive docs at /docs on any running instance.

Family management

GET    /api/v1/families/me                     # All families the current user belongs to
POST   /api/v1/families/                       # Create a new family
GET    /api/v1/families/{id}/members            # List family members
POST   /api/v1/families/{id}/members            # Invite a member by email
DELETE /api/v1/families/{id}/members/{user_id}   # Remove a member

Quick examples

# Register
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Test User","email":"test@example.com","password":"Password123!"}'

# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"Password123!"}'

# Create a family
curl -X POST http://localhost:8000/api/v1/families/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"The Sharma Family"}'

# Invite a member
curl -X POST http://localhost:8000/api/v1/families/<id>/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"email":"member@example.com","role":"member"}'

Testing

cd backend
pytest                 # run the test suite
pytest --cov=app        # with coverage

Every push to main/staging and every pull request runs the CI pipeline (.github/workflows/ci-cd.yml): backend lint (black, isort, flake8), frontend lint, and the test suite. PRs must pass pr-check.yml before merge.

Contributing

Contributions of any size are welcome — bug fixes, new features, docs improvements, or just filing a well-written issue.

Fork the repository and clone your fork
Branch off main: git checkout -b feature/add-csv-import
Run make setup to get a working local environment
Make your changes, following the existing layered architecture (route → service → repository)
Run make lint and make test before pushing

Commit using Conventional Commits:

feat:      new feature
fix:       bug fix
docs:      documentation changes
refactor:  code restructure, no behavior change
test:      adding or fixing tests
chore:     build, deps, config changes

Push and open a Pull Request against main using the provided template
Link any related issue and describe what you tested

Bug reports and feature requests use the templates in .github/ISSUE_TEMPLATE — please use them, it makes triage much faster.

Not sure where to start? Look for issues tagged good first issue, or open a discussion if you'd like to propose something larger before writing code.

Roadmap

CSV/OFX transaction import
Multi-currency support
Mobile app (React Native)
Shared family calendar for recurring bills
Webhooks for external accounting tools

Have an idea? Open a feature request.

License

Distributed under the MIT License. See LICENSE for details.

Acknowledgements

Built with:

FastAPI — modern Python web framework
SQLAlchemy — Python SQL toolkit
Google Gemini — AI financial advisor
Recharts — React charting library
Render — backend hosting
Vercel — frontend hosting

If this project is useful to you, consider giving it a ⭐ — it helps others find it.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github		.github
backend		backend
docker		docker
docs		docs
frontend		frontend
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

🏦 Family Office

Table of Contents

About

Screenshots

Features

💰 Core Financial Management

👪 Family Workspace

🤖 AI & Analytics

🔒 Security

🎨 UI/UX

Tech Stack

Architecture

Project Structure

Getting Started

Prerequisites

1. Clone and configure

2. Run everything with Docker (recommended)

2b. Backend only

2c. Frontend only

3. Access the application

Environment Variables

Backend

Frontend

Useful Make Commands

Deployment

Backend → Render

Frontend → Vercel

API Reference

Family management

Quick examples

Testing

Contributing

Roadmap

License

Acknowledgements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages