Uncap Data B2B Application (Next.js & FastAPI)

This is the main B2B application for Uncap Data, now re-architected with a Next.js frontend and a FastAPI backend. It provides a comprehensive platform for businesses to access and leverage data insights, integrating various data products and offering robust administrative capabilities.

Architecture

This application is built on a modern, decoupled architecture:

• Frontend: Developed with Next.js (React, TypeScript) for a fast, interactive, and scalable user interface.
• Backend: Powered by FastAPI (Python) for high-performance API services, handling business logic, data processing, and database interactions.

Key Features

The Uncap Data B2B application is built around three core data products, designed to provide targeted insights:

• ProductLens: Provides in-depth analysis and insights into product performance and market trends. (Functionality being migrated/implemented).
• PropertyPulseIQ: Offers real-time property market intelligence, including valuation, investment opportunities, and demographic data. (Currently a placeholder, functionality to be implemented).
• WayScan IQ: Delivers advanced scanning and intelligence capabilities for competitive analysis and market surveillance.

Beyond the core products, the application includes:

• Authentication: Secure login integrated with Microsoft Entra External ID (formerly Azure AD B2C/CIAM) using JWTs.
• User Management: Tools for managing user access and subscriptions across different products.
• Containerization: Dockerfile and Docker Compose setup for easy deployment of the FastAPI backend.
• API-driven: All frontend-backend communication is via RESTful APIs.

Admin Portal Features

The application also incorporates a powerful administrative portal for managing the underlying data and system configurations:

• CRUD Operations: Full Create, Read, Update, Delete functionality for various SQLAlchemy-defined models (Companies, Products, Organizations, Subscriptions, Users, AdminScopes, ProductLens, UserSubscriptions, ScanIQCategories, etc.).
• User Provisioning: Ability to invite new users to the Entra External ID tenant directly from the application.
• Dynamic Related Entity Creation: Create new Companies or Organizations directly from the User or Organization creation forms.
• Data Navigation: Pagination, sorting, filtering, and search capabilities for large datasets.

Setup and Installation

Prerequisites

• Node.js (LTS version recommended) and npm (or yarn/pnpm/bun).
• Python 3.9+ and uv (or pip).
• Docker Desktop (for Docker/Docker Compose methods for backend).
• Access to an Azure subscription and a Microsoft Entra External ID tenant.
• An Azure SQL Database instance.
• wkhtmltopdf: Required for PDF generation in ProductLens. Install it on your system and ensure it's in your PATH.

1. Environment Variables (.env)

Create a .env file in the uncapreactapp/backend directory and populate it with your specific configuration. This file is for the FastAPI backend.

# .env (in uncapreactapp/backend/)

# FastAPI Secret Key (generate a strong, random one for JWTs)
SECRET_KEY=your_super_secret_fastapi_key_here

# Main Database Configuration
DB_USER=your_db_username
DB_PASSWORD=your_db_password
DB_HOST=your_sql_server_name.database.windows.net
DB_NAME=your_database_name
DB_DRIVER=ODBC Driver 18 for SQL Server # Ensure this driver is installed on your system/container

# Product Database Configuration (if applicable)
PRODUCT_DB_USER=your_product_db_username
PRODUCT_DB_PASSWORD=your_product_db_password
PRODUCT_DB_HOST=your_product_sql_server_name.database.windows.net
PRODUCT_DB_NAME=your_product_database_name
PRODUCT_DB_DRIVER=ODBC Driver 18 for SQL Server # Ensure this driver is installed on your system/container

# Microsoft Entra External ID (Azure AD) Configuration
CLIENT_ID=your_application_client_id_guid
CLIENT_SECRET=your_application_client_secret
TENANT_ID=your_entra_id_tenant_guid # The GUID of your Entra ID tenant
TENANT_NAME=your_tenant_name # e.g., 'uncapdata' if your domain is uncapdata.onmicrosoft.com
USER_FLOW_NAME=your_user_flow_name # e.g., 'uncap_signin' (the name of your sign-up/sign-in user flow)
APP_URL=http://localhost:3000 # For local development, this is your Next.js frontend URL

# Azure Communication Services (for email/SMS notifications)
ACS_CONNECTION_STRING=your_acs_connection_string
ACS_SENDER_ADDRESS=your_acs_sender_address

# Azure Blob Storage (for file uploads/storage)
AZURE_STORAGE_CONNECTION_STRING=your_azure_storage_connection_string
AZURE_STORAGE_CONTAINER_NAME=your_azure_storage_container_name

# Discord Webhook URLs (for notifications/logging - optional)
DISCORD_WEBHOOK_URL=your_general_discord_webhook_url
DISCORD_LOGIN_WEBHOOK=your_login_discord_webhook_url
DISCORD_ERROR_WEBHOOK=your_error_discord_webhook_url
DISCORD_WARNING_WEBHOOK=your_warning_discord_webhook_url

Important Azure AD Setup Steps:

• App Registration: Register your application in the Azure portal.
  • Supported Account Types: Choose an option that allows external identities (e.g., "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts").
  • Redirect URIs: Add http://localhost:3000/api/auth/get_token (for local) and https://your-app-domain.com/api/auth/get_token (for Azure) as "Web" platform redirect URIs.
  • Client Secret: Generate a client secret and copy its value into CLIENT_SECRET in your .env.
  • API Permissions: Grant "Application Permissions" for "Microsoft Graph": User.Read.All and User.Invite.All. Remember to click "Grant admin consent for [Your Tenant Name]".
• User Flows: Create a "Sign up and sign in" user flow in your Entra External ID tenant and use its name for USER_FLOW_NAME.
• External Collaboration Settings: Ensure your tenant's external collaboration settings allow guest invitations to any domain.

2. Install Dependencies

For the FastAPI Backend:

Navigate to the uncapreactapp/backend directory and install Python dependencies:

cd uncapreactapp/backend
uv pip install -r requirements.txt # Or pip install -r requirements.txt

For the Next.js Frontend:

Navigate to the uncapreactapp directory and install Node.js dependencies:

cd uncapreactapp
npm install # Or yarn install / pnpm install / bun install

3. Database Migrations (FastAPI Backend)

Database migrations are now managed within the FastAPI backend. You will need a tool like Alembic for SQLAlchemy. (This setup is not yet fully integrated into the FastAPI project, refer to TODO.md for details).

Running the Application

1. Start the FastAPI Backend

From the project root directory (uncapreactapp/), run the FastAPI application:

uvicorn backend.main:app --reload --port 8000

The backend will be accessible at http://localhost:8000.

2. Start the Next.js Frontend

Navigate to the uncapreactapp directory and start the Next.js development server:

cd uncapreactapp
npm run dev

The frontend will be accessible at http://localhost:3000.

Deployment

Deployment will involve deploying the FastAPI backend and the Next.js frontend separately.

• FastAPI Backend: Can be deployed to platforms like Azure App Service (Linux Container), Azure Container Apps, or Kubernetes.
• Next.js Frontend: Can be deployed to platforms like Vercel, Netlify, or any Node.js hosting environment.

Refer to the TODO.md file for more detailed deployment considerations and remaining tasks.

Deployment to Azure Static Web Apps

This application is designed to be deployed to Azure Static Web Apps, which can host both the Next.js frontend and the FastAPI backend in a serverless environment.

1. Local Configuration

Ensure your next.config.ts file does not contain the output: 'export' line. The standard Next.js server-based output is required for Azure to build the app correctly into static assets and serverless functions.

2. How to Build and Test Locally for Production

Before deploying, you can run a production-like build and test the application's behavior locally using the Azure Static Web Apps CLI. This provides the closest simulation of the Azure environment.

1. Install the Azure Static Web Apps CLI (if you haven't already):

   npm install -g @azure/static-web-apps-cli

2. Ensure your FastAPI backend is running in a separate terminal:

   uvicorn backend.main:app --reload --port 8000

3. Build the Next.js frontend for production:

   npm run build

4. Start the Azure Static Web Apps emulator: Navigate to your project root (uncapplatform/) and run:

   swa start .next --port 3000

   • The frontend will be accessible at http://localhost:3000.
   • This command will serve your Next.js build output, proxy API calls to your local FastAPI backend, and emulate the Azure Static Web Apps environment.

3. Azure Deployment Steps

1. Push to GitHub: Make sure your application code is in a GitHub repository.
2. Create Static Web App: In the Azure Portal, create a new "Static Web App" resource.
3. Connect to GitHub: Link the Static Web App to your GitHub repository and branch.
4. Configure Build Settings: In the "Build" tab of the creation wizard, use the following settings:
   • Build Presets: Select Next.js.
   • App location: / (This should be the root of your repository where package.json is).
   • Api location: backend (This tells Azure where your Python FastAPI code is).
   • Output location: Leave blank. The Next.js preset handles this automatically.
5. Set Environment Variables: After the resource is created, go to its "Configuration" section. Add all the environment variables from your local .env file (e.g., DB_USER, CLIENT_ID, SECRET_KEY, etc.) here. This is a critical step for the backend API to function correctly.
6. Review and Create: Complete the wizard. Azure will create a GitHub Actions workflow file in your repository (.github/workflows) that will automatically build and deploy your app whenever you push changes to the selected branch.