wealth-map

Wealth Map

A comprehensive wealth management and property analysis platform built with Next.js, Prisma, and modern web technologies.

Features

Role-Based Access Control (RBAC)
- SUPER_ADMIN: Full system access
- COMPANY_ADMIN: Company-level management
- EMPLOYEE: Basic access with customizable permissions
Property Management
- Property search and filtering
- Property details and analytics
- Bookmarking system
- Trending properties
Reporting System
- Custom report generation
- Export in multiple formats (CSV, Excel, JSON)
- Report history and management
- Export preview functionality

Tech Stack

Frontend
- Next.js 15
- React 18
- Tailwind CSS
- Radix UI Components
- Framer Motion
- Recharts
Backend
- Next.js API Routes
- Prisma ORM
- PostgreSQL Database
- NextAuth.js v5 for Authentication

Prerequisites

Node.js 20+
PostgreSQL 15+
Redis (for caching)
Google AI API Key
GROQ API Key
MapTiler API Key

Environment Variables

Create a .env file in the root directory with the following variables:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/wealth_map"

# Authentication
NEXTAUTH_URL="http://localhost:3000"
AUTH_SECRET="your-secret-key"

# Redis Cache
REDIS_URL="redis://localhost:6379"

# AI Services
GOOGLE_AI_API_KEY="your-google-ai-key"
GROQ_API_KEY="your-groq-key"

# Map Services
MAPTILER_API_KEY="your-maptiler-key"

# Email (Optional for email-based features)
RESEND_API_KEY="your-resend-api-key"
EMAIL_FROM="no-reply@your-domain.com"

Installation

Clone the repository:

git clone https://github.com/yourusername/wealth-map.git
cd wealth-map

Install dependencies:
```
npm install
```
Set up the database and generate Prisma client:
```
npx prisma generate
npx prisma migrate dev
```
Seed the database with initial data:
```
npm run seed
```
Start the development server:
```
npm run dev
```
Access the application:
- Open your browser and navigate to http://localhost:3000
- Default login credentials:
  - Email: admin@example.com
  - Password: password123

Project Architecture

Directory Structure

wealth-map/
├── prisma/               # Database schema and migrations
├── public/               # Static assets
├── src/
│   ├── app/              # Next.js App Router components
│   │   ├── api/          # API routes
│   │   ├── app/          # Main application routes
│   │   │   ├── employee/ # Employee-specific pages
│   │   │   ├── company-admin/ # Company admin pages
│   │   │   └── super-admin/ # Super admin pages
│   │   └── auth/         # Authentication pages
│   ├── components/       # React components
│   │   ├── custom-components/ # Application-specific components
│   │   └── ui/           # UI component library
│   ├── hooks/            # React hooks
│   ├── lib/              # Utility functions and libraries
│   ├── Models/           # TypeScript models and interfaces
│   ├── services/         # API service classes
│   ├── stores/           # Global state management
│   ├── types/            # TypeScript type definitions
│   └── middleware.ts     # Next.js middleware for auth and routing

Core Components

Component	Purpose	Key Features
`AppSidebar`	Main navigation	• Role-based navigation items • Collapsible UI • User profile integration
`PropertyExport`	Property data export	• Multi-format export • Field selection • Preview functionality
`InteractiveMap`	Property visualization	• MapTiler integration • Property filtering • Custom markers
`HomePage`	Employee dashboard	• Property search • Saved views • Analytics dashboard

Authentication Flow

Login Process
- User enters credentials
- Server validates credentials and checks 2FA status
- Session token generated and stored
- User redirected based on role
Authorization Flow
- Middleware checks user session
- Routes protected based on role
- Permission-based component rendering
- API routes secured by permission checks

Data Flow

Export Process

Selection Phase
- User selects properties
- Chooses export format
- Selects fields to export
Processing Phase
- Data validation
- Format conversion
- File generation
Storage Phase
- Save to export history
- Generate download URL
- Update UI state

API Integration

// Example API endpoints
POST /api/reports/export
GET /api/reports/export
DELETE /api/reports/export?id={id}

Development Guidelines

Code Style

Component Structure

// Component template
export default function ComponentName() {
  // 1. Hooks and state
  const [state, setState] = useState()
     
  // 2. Helper functions
  const helperFunction = () => {}
     
  // 3. Event handlers
  const handleEvent = () => {}
     
  // 4. Render
  return (
    <div>
      {/* JSX */}
    </div>
  )
}

Permission Checks

// Always wrap permission-dependent components
<WithPermission permission="required:permission">
  <Component />
</WithPermission>

State Management

Local State
- Use useState for component-level state
- Use useReducer for complex state logic
Global State
- Use context for shared state
- Implement proper state updates

Error Handling

API Errors

try {
  const response = await fetch('/api/endpoint')
  if (!response.ok) {
    throw new Error('API Error')
  }
} catch (error) {
  toast({
    title: "Error",
    description: "User-friendly message",
    variant: "destructive"
  })
}

Validation

// Input validation
const validateInput = (input: string) => {
  if (!input) {
    throw new Error('Required field')
  }
}

Permissions and Access Control

Role Hierarchy

Role	Description	Key Capabilities
SUPER_ADMIN	System-level access	• Manage all companies and users • Access all features and settings • Create system-wide roles • Override any permission
COMPANY_ADMIN	Company-level access	• Manage company employees • Access company properties and reports • Create company-specific roles • Manage company settings
EMPLOYEE	Basic access	• Access assigned properties • View permitted reports • Customizable permissions • Role-based access

Permission Matrix

Category	Permission	Description	SUPER_ADMIN	COMPANY_ADMIN	EMPLOYEE
System	`system:*`	Full system access	✓	-	-
	`system:settings`	View/modify settings	✓	-	-
	`system:maintenance`	Maintenance controls	✓	-	-
	`system:logs`	Access system logs	✓	-	-
Property	`property:*`	Full property access	✓	✓	-
	`property:view`	View properties	✓	✓	✓
	`property:search`	Search properties	✓	✓	✓
	`property:create`	Create properties	✓	✓	-
	`property:edit`	Edit properties	✓	✓	-
	`property:delete`	Delete properties	✓	✓	-
	`property:bookmark`	Bookmark properties	✓	✓	✓
Reports	`reports:*`	Full report access	✓	✓	-
	`reports:view`	View reports	✓	✓	✓
	`reports:create`	Create reports	✓	✓	✓
	`reports:edit`	Edit reports	✓	✓	-
	`reports:delete`	Delete reports	✓	✓	-
	`reports:export`	Export reports	✓	✓	✓
	`reports:schedule`	Schedule reports	✓	✓	-
Users	`users:*`	Full user management	✓	-	-
	`users:view`	View users	✓	✓	-
	`users:create`	Create users	✓	✓	-
	`users:edit`	Edit users	✓	✓	-
	`users:delete`	Delete users	✓	-	-
	`users:roles`	Manage roles	✓	✓	-
Company	`company:*`	Full company access	✓	✓	-
	`company:view`	View company info	✓	✓	-
	`company:edit`	Edit company	✓	✓	-
	`company:employees`	Manage employees	✓	✓	-
	`company:roles`	Manage roles	✓	✓	-

Permission Implementation

// Example permission check in API route
const hasPermission = user.roles.some(role =>
  role.permissions.some(p => p.name === "property:view")
);

// Example permission check in React component
<WithPermission permission="reports:create">
  <ExportButton />
</WithPermission>

// Example conditional rendering
{hasPermission("property:edit") && (
  <EditPropertyButton />
)}

Best Practices

Least Privilege
- Assign minimum required permissions
- Regular permission audits
- Remove unused permissions
Security
- Validate on both client and server
- Use middleware for checks
- Log permission changes
Role Design
- Create roles based on job functions
- Use descriptive role names
- Document permission assignments
Maintenance
- Regular permission audits
- Update roles as requirements change
- Document permission changes

Troubleshooting

Common Issues

Database Connection Errors
- Ensure PostgreSQL is running
- Verify DATABASE_URL in .env file
- Check for correct database credentials
```
# Test database connection
npx prisma db pull
```
Authentication Issues
- Verify NEXTAUTH_SECRET is set
- Check user roles and permissions
- Clear browser cookies and try again
- Ensure email verification is working (if enabled)
Map Not Loading
- Verify MAPTILER_API_KEY is valid
- Check browser console for errors
- Ensure MapTiler account has sufficient quota
AI Features Not Working
- Verify AI API keys are valid
- Check usage limits on AI service providers
- Look for specific error messages in server logs

Debugging

# Check Prisma database connection
npx prisma db pull

# Reset database (development only)
npx prisma migrate reset

# Validate environment variables
node -e "console.log(process.env.DATABASE_URL)"

# Check for TypeScript errors
npx tsc --noEmit

Deployment

Build and Start Production Server

# Build the application
npm run build

# Start the production server
npm run start

Continuous Integration/Deployment

For CI/CD setup, you can use services like Vercel, Netlify, or a custom pipeline:

Vercel Deployment

Connect your GitHub repository to Vercel
Configure environment variables in the Vercel dashboard
Deploy automatically on push to main branch

Docker Deployment

# Build Docker image
docker build -t wealth-map .

# Run Docker container
docker run -p 3000:3000 --env-file .env.production wealth-map

Database Migration in Production

# Apply migrations to production database
npx prisma migrate deploy

# If needed, seed production data
NODE_ENV=production npm run seed

Important Production Considerations

Set up proper database backups
Configure Redis for production with authentication
Use a reverse proxy like Nginx for SSL termination
Implement rate limiting for API endpoints
Set up monitoring and error tracking