urbanrealestateapi-o2lsw0/README.md

# Urban Real Estate API

A comprehensive backend API for the Urban Real Estate App - a Nigerian housing marketplace that connects property seekers with agents, landlords, and affordable housing options.

## Features

- **User Authentication & Authorization**: JWT-based authentication with role-based access control
- **Property Listings Management**: Full CRUD operations for property listings
- **Affordable Housing**: Dedicated endpoints for affordable housing listings
- **Messaging System**: Real-time messaging between users
- **Admin Dashboard**: Administrative controls for managing users and properties
- **Notifications**: User notification system
- **Payment Integration**: Paystack payment gateway integration
- **Search & Filtering**: Advanced property search with multiple filters

## Technology Stack

- **Framework**: FastAPI (Python)
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **API Documentation**: Automatic OpenAPI/Swagger documentation
- **Migrations**: Alembic for database migrations

## Project Structure

```
urbanrealestateapi/
├── app/
│   ├── auth/                 # Authentication utilities
│   ├── core/                 # Core security functions
│   ├── db/                   # Database configuration
│   ├── models/               # SQLAlchemy models
│   ├── routers/              # API route handlers
│   └── schemas/              # Pydantic schemas
├── alembic/                  # Database migrations
├── main.py                   # FastAPI application entry point
├── requirements.txt          # Python dependencies
└── README.md                 # This file
```

## Installation & Setup

1. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

2. **Set Environment Variables**:
   ```bash
   export SECRET_KEY="your-secret-key-here"
   export PAYSTACK_SECRET_KEY="your-paystack-secret-key"
   export PAYSTACK_PUBLIC_KEY="your-paystack-public-key"
   export ENVIRONMENT="development"
   ```

3. **Run Database Migrations**:
   ```bash
   alembic upgrade head
   ```

4. **Start the Application**:
   ```bash
   uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   ```

## Environment Variables

The following environment variables should be set for production:

- `SECRET_KEY`: JWT secret key for token generation
- `PAYSTACK_SECRET_KEY`: Paystack secret key for payment processing
- `PAYSTACK_PUBLIC_KEY`: Paystack public key for payment processing
- `ENVIRONMENT`: Application environment (development/production)

## API Endpoints

### Authentication
- `POST /api/auth/register` - Register a new user
- `POST /api/auth/login` - Login user

### Properties
- `GET /api/properties/` - List properties with filtering
- `POST /api/properties/` - Create new property listing
- `GET /api/properties/{id}` - Get property details
- `PUT /api/properties/{id}` - Update property listing
- `DELETE /api/properties/{id}` - Delete property listing

### Affordable Housing
- `GET /api/affordable/` - List affordable housing properties

### Messages
- `POST /api/messages/` - Send a message
- `GET /api/messages/` - Get user messages
- `GET /api/messages/conversations/{user_id}` - Get conversation with specific user
- `PUT /api/messages/{id}/read` - Mark message as read

### Notifications
- `GET /api/notifications/` - Get user notifications
- `PUT /api/notifications/{id}/read` - Mark notification as read
- `PUT /api/notifications/mark-all-read` - Mark all notifications as read

### Admin (Admin role required)
- `GET /api/admin/properties/pending` - Get pending property approvals
- `PUT /api/admin/properties/{id}/approve` - Approve property listing
- `PUT /api/admin/properties/{id}/reject` - Reject property listing
- `GET /api/admin/users` - List users
- `PUT /api/admin/users/{id}/deactivate` - Deactivate user
- `GET /api/admin/analytics` - Get system analytics

### Payments
- `POST /api/payments/initiate` - Initiate payment
- `POST /api/payments/verify/{ref}` - Verify payment
- `GET /api/payments/` - Get user payments
- `GET /api/payments/{id}` - Get payment details

### System
- `GET /` - API information
- `GET /health` - Health check endpoint
- `GET /docs` - Swagger documentation
- `GET /redoc` - ReDoc documentation

## User Roles

1. **Seeker**: Can search and view properties, send messages
2. **Agent**: Can list properties, manage listings, communicate with seekers
3. **Landlord**: Can list properties, manage listings, communicate with seekers
4. **Admin**: Full access to all endpoints, can approve/reject listings, manage users

## Database Schema

### Users
- User authentication and profile information
- Role-based access control
- Profile with bio, image, and verification status

### Properties
- Property listings with comprehensive details
- Location, pricing, and amenity information
- Approval workflow for listings
- Support for affordable housing categorization

### Messages
- Real-time messaging between users
- Message read status tracking

### Notifications
- User notification system
- Read/unread status tracking

### Payments
- Payment transaction logging
- Paystack integration support

## Development

### Running Tests
```bash
# Add your test commands here when tests are implemented
pytest
```

### Code Formatting
```bash
ruff check .
ruff format .
```

### Database Operations
```bash
# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1
```

## Production Deployment

1. Set all required environment variables
2. Use a production WSGI server like Gunicorn
3. Configure proper database (PostgreSQL recommended for production)
4. Set up proper logging and monitoring
5. Configure HTTPS/SSL
6. Set up database backups

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## License

This project is licensed under the MIT License.

## Support

For support and questions, please create an issue in the repository.