Borbann Project

A data integration and analysis platform focused on real estate.

Project Structure

• /backend: Contains the Python FastAPI backend application, background workers, and database models.
• /frontend: Contains the Next.js (React/TypeScript) frontend application.

Prerequisites

Ensure you have the following installed on your system:

• Node.js: (Specify version, e.g., v20.x or later)
• pnpm: (Specify version or npm install -g pnpm)
• Python: (Specify version, e.g., v3.11 or v3.12, matching .python-version if present)
• Docker: Latest version
• Docker Compose: Latest version (often included with Docker Desktop)
• Database Client: (Optional, for direct DB access, e.g., psql for PostgreSQL)

Environment Setup

Both frontend and backend might require environment variables.

1. Backend:
   • Navigate to the backend directory: cd backend
   • Create a .env file by copying .env.example: cp .env.example .env
   • Crucially, fill in the required values in .env, especially secrets like database passwords and API keys. Never commit your .env file to Git.
2. Frontend:
   • Navigate to the frontend directory: cd frontend
   • Create a .env.local file if needed (e.g., for NEXT_PUBLIC_API_URL). Copy from .env.example if one exists. Do not commit .env.local files containing secrets.

(See .env.example files in respective directories for required variables)

Setup Instructions

1. Backend Setup

# Navigate to the backend directory
cd backend

# Create and activate a virtual environment (recommended)
python -m venv .venv
# Windows:
# .\ .venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies (uses pyproject.toml)
pip install -e .

# Or if requirements.txt is preferred:
# pip install -r requirements.txt

# Set up the database (Run Docker Compose first if DB is containerized)
# Example assuming Alembic migrations (add if you use Alembic)
# alembic upgrade head

2. Frontend Setup

# Navigate to the frontend directory
cd frontend

# Install dependencies using pnpm
pnpm install

Running the Application

Development Mode

You typically need multiple terminals for development.

1. Start Docker Services (Database, Redis, etc.):

   # From the 'backend' directory
   docker-compose up -d db redis # Add other services as needed
   

2. Start Backend API:

   # From the 'backend' directory (with virtual env activated)
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

   (The API will be accessible at http://localhost:8000)

3. Start Celery Worker (if needed for background tasks):

   # From the 'backend' directory (with virtual env activated)
   celery -A app.workers.celery_app worker --loglevel=info
   

4. Start Celery Beat (if using scheduled tasks):

   # From the 'backend' directory (with virtual env activated)
   celery -A app.workers.celery_app beat --loglevel=info --scheduler django_celery_beat.schedulers:DatabaseScheduler
   # Or if not using DB scheduler:
   # celery -A app.workers.celery_app beat --loglevel=info
   

5. Start Frontend:

   # From the 'frontend' directory
   pnpm dev
   

   (The frontend will be accessible at http://localhost:3000)

Production Mode (Using Docker)

# Navigate to the 'backend' directory (or project root if compose file is there)
cd backend

# Build the Docker images
docker-compose build

# Start all services in detached mode
docker-compose up -d

# To stop the services
docker-compose down

Building for Production

Backend

Python code doesn't typically require a separate build step unless you are creating a distributable package. Docker handles the "build" in the context of creating an image.

Frontend

# Navigate to the frontend directory
cd frontend

# Create a production build
pnpm build

This will create an optimized build in the .next directory. Use pnpm start to run this build.

Testing

Backend

# Navigate to the backend directory (with virtual env activated)
pytest

(Ensure test database is configured and any necessary test setup is performed)

Frontend

# Navigate to the frontend directory
pnpm test

(Add specific test commands if using Jest, Cypress, etc.)

Linting and Formatting

Backend

# Navigate to the backend directory (with virtual env activated)
# Check formatting
black --check .
# Format code
black .

# Check linting/imports
ruff check .
# Fix linting/imports where possible
ruff check . --fix

Frontend

# Navigate to the frontend directory
# Check linting
pnpm lint

# Check/Apply formatting (assuming Prettier is setup)
pnpm prettier --check .
pnpm prettier --write .

Deployment

• Backend: Can be deployed using Docker containers on services like AWS ECS, Google Cloud Run, Kubernetes, etc. Ensure environment variables are securely managed.
• Frontend: The Next.js application can be easily deployed to platforms like Vercel (recommended), Netlify, AWS Amplify, or self-hosted using Node.js or Docker.