Skip to content

ponnarasua/FRA

BranchesTags

Repository files navigation

Smart FRA Atlas - Complete Project Setup Guide

A comprehensive Smart Forest Rights Act (FRA) Atlas system with AI-powered document processing, interactive mapping, and decision support capabilities.

🏗️ Project Architecture

FRA/
├── backend/           # FastAPI backend with AI/ML services
├── frontend/          # React frontend application  
├── OCR/              # Standalone OCR processing service
├── ARCHITECTURE.md   # System architecture documentation
└── README.md         # This file

🚀 Complete Setup Instructions

Prerequisites

Before starting, ensure you have the following installed:

  • Python 3.10+ (for backend and OCR services)
  • Node.js 18+ (for frontend)
  • PostgreSQL 14+ with PostGIS extension
  • Git for version control
  • Windows PowerShell or Command Prompt

📋 Quick Start Checklist

  • Install Python 3.10+
  • Install Node.js 18+
  • Install PostgreSQL with PostGIS
  • Clone the repository
  • Set up backend environment
  • Set up frontend environment
  • Configure database
  • Start all services

🔧 Detailed Setup Instructions

1. System Dependencies Installation

Python Installation

# Download from https://python.org (Python 3.10 or higher)
# Verify installation
python --version
pip --version

Node.js Installation

# Download from https://nodejs.org (LTS version)
# Verify installation
node --version
npm --version

PostgreSQL with PostGIS

# Download from https://postgresql.org
# During installation, include PostGIS extension
# Note down the database credentials

2. Project Setup

Clone Repository

git clone https://github.com/ponnarasua/FRA.git
cd FRA

Project Structure Verification

# Verify all directories exist
ls
# Should show: backend/, frontend/, OCR/, README.md, ARCHITECTURE.md

3. Backend Setup (FastAPI + AI/ML Services)

Navigate to Backend

cd backend

Create Python Virtual Environment

# Create virtual environment
python -m venv fra_backend_env

# Activate virtual environment
# For PowerShell:
fra_backend_env\Scripts\Activate.ps1

# For Command Prompt:
fra_backend_env\Scripts\activate.bat

# Verify activation (should show (fra_backend_env) in prompt)

Install Python Dependencies

# Upgrade pip first
python -m pip install --upgrade pip

# Install all backend dependencies
pip install -r requirements.txt

# This will install:
# - FastAPI and Uvicorn (web framework)
# - SQLAlchemy and Alembic (database)
# - PostGIS and GeoAlchemy2 (spatial data)
# - PaddleOCR (OCR processing)
# - SpaCy and Transformers (NLP)
# - Scikit-learn (machine learning)
# - And many more dependencies

Database Setup

# Create database (run in PostgreSQL command line or pgAdmin)
# Replace 'your_password' with your actual password
createdb -U postgres fra_atlas_db

# Enable PostGIS extension (in psql or pgAdmin)
psql -U postgres -d fra_atlas_db -c "CREATE EXTENSION postgis;"

Environment Configuration

# Create .env file in backend directory
# Copy the following content to .env file:

DATABASE_URL=postgresql://postgres:your_password@localhost:5432/fra_atlas_db
SECRET_KEY=your-secret-key-here-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
ENVIRONMENT=development
DEBUG=True
CORS_ORIGINS=["http://localhost:5173", "http://localhost:3000"]

Database Migration

# Initialize Alembic (if not done)
alembic init alembic

# Create initial migration
alembic revision --autogenerate -m "Initial migration"

# Apply migrations
alembic upgrade head

Download NLP Models

# Download SpaCy English model
python -m spacy download en_core_web_sm

# Download additional models if needed
python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords')"

4. Frontend Setup (React Application)

Navigate to Frontend (in new terminal)

# Open new PowerShell window
cd "D:\New folder\FRA\frontend"

Install Node.js Dependencies

# Install all frontend dependencies
npm install

# This will install:
# - React 19 and React DOM
# - Vite (build tool)
# - Tailwind CSS (styling)
# - React Router (navigation)
# - Chart.js (data visualization)
# - React Leaflet (mapping)
# - Axios (API calls)
# - And many more dependencies

Environment Configuration

# Create .env file in frontend directory
# Add the following content:

VITE_API_BASE_URL=http://localhost:8000
VITE_APP_NAME=Smart FRA Atlas
VITE_APP_VERSION=1.0.0
VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here

5. OCR Service Setup (Optional Standalone Service)

Navigate to OCR Directory

cd "D:\New folder\FRA\OCR"

Create OCR Virtual Environment

# Create separate environment for OCR
python -m venv Clean

# Activate environment
Clean\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

🚦 Running the Complete System

Starting All Services

1. Start Backend API Server

# In backend directory with activated virtual environment
cd "D:\New folder\FRA\backend"
fra_backend_env\Scripts\Activate.ps1

# Start FastAPI server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Server will start at: http://localhost:8000
# API docs available at: http://localhost:8000/docs

2. Start Frontend Development Server

# In new PowerShell window - frontend directory
cd "D:\New folder\FRA\frontend"

# Start Vite development server
npm run dev

# Frontend will start at: http://localhost:5173

3. Start OCR Service (Optional)

# In new PowerShell window - OCR directory
cd "D:\New folder\FRA\OCR"
Clean\Scripts\Activate.ps1

# Start OCR service
python main.py

# OCR service will start at specified port

📱 Accessing the Application

Once all services are running:

  1. Frontend Application: http://localhost:5173

    • Main user interface
    • Dashboard, Atlas, Analytics, etc.

  2. Backend API: http://localhost:8000

  3. Database: localhost:5432

    • PostgreSQL with PostGIS
    • Database name: fra_atlas_db

🔍 Service Status Verification

Check Backend Health

# Test API health endpoint
curl http://localhost:8000/api/system/health

# Or visit in browser:
# http://localhost:8000/docs

Check Frontend

# Visit in browser:
# http://localhost:5173

# Should show Smart FRA Atlas dashboard

Check Database Connection

# Connect to database
psql -U postgres -d fra_atlas_db

# List tables
\dt

# Check PostGIS
SELECT PostGIS_Version();

🐛 Troubleshooting Common Issues

Backend Issues

Python Dependencies

# If pip install fails, try:
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt --no-cache-dir

Database Connection

# Check PostgreSQL service is running
Get-Service -Name postgresql*

# Test database connection
psql -U postgres -h localhost -p 5432 -d fra_atlas_db

Port Already in Use

# Kill process on port 8000
netstat -ano | findstr :8000
taskkill /PID <PID_NUMBER> /F

# Or use different port
uvicorn app.main:app --reload --port 8001

Frontend Issues

Node Dependencies

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Port Already in Use

# Kill process on port 5173
netstat -ano | findstr :5173
taskkill /PID <PID_NUMBER> /F

# Or Vite will automatically use next available port

API Connection Issues

# Check backend is running
curl http://localhost:8000/api/system/health

# Verify CORS settings in backend .env file

General Issues

Virtual Environment

# If activation fails
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then try activating again
fra_backend_env\Scripts\Activate.ps1

File Permissions

# Run PowerShell as Administrator if needed
# Check file permissions in project directory

📊 Application Features

Dashboard

  • Real-time FRA claim statistics
  • Recent activity feed
  • Quick action buttons
  • Performance metrics visualization

FRA Atlas (Interactive Mapping)

  • Geographic visualization of claims
  • Multiple map layers (satellite, boundaries)
  • Spatial search and filtering
  • Claim status visualization

Document Upload & OCR

  • Drag-and-drop file upload
  • Automatic text extraction
  • Entity recognition (names, places, dates)
  • Document processing statistics

Analytics & Reporting

  • Comprehensive claim analytics
  • Processing time analysis
  • Geographic distribution
  • Trend analysis and forecasting
  • Export capabilities

AI-Powered Decision Support

  • Automated claim recommendations
  • Risk assessment scoring
  • Evidence-based reasoning
  • Processing time predictions

🔒 Security Notes

Development Environment

  • Use strong passwords for database
  • Change default secret keys
  • Enable CORS only for development URLs
  • Keep dependencies updated

Production Deployment

  • Use environment variables for secrets
  • Enable HTTPS/SSL
  • Configure proper CORS origins
  • Set up database backups
  • Monitor system logs

📞 Support & Help

Getting Help

  1. Check this README for common issues
  2. Review the ARCHITECTURE.md file
  3. Check individual service README files
  4. Create GitHub issues for bugs
  5. Contact development team

Development Commands Quick Reference

# Backend
cd backend
fra_backend_env\Scripts\Activate.ps1
uvicorn app.main:app --reload

# Frontend  
cd frontend
npm run dev

# Database migrations
alembic upgrade head

# Install new Python package
pip install package_name
pip freeze > requirements.txt

# Install new Node package
npm install package_name

🎯 Next Steps After Setup

  1. Access the Dashboard at http://localhost:5173
  2. Explore the Atlas for interactive mapping
  3. Upload test documents to try OCR functionality
  4. Review analytics for system insights
  5. Check DSS recommendations for AI features

📈 Project Status

  • ✅ Backend API with 50+ endpoints
  • ✅ Frontend React application
  • ✅ Database models and migrations
  • ✅ AI/ML services integration
  • ✅ Interactive mapping
  • ✅ Document processing pipeline
  • ✅ Analytics and reporting
  • ✅ Decision support system

The Smart FRA Atlas is ready for development and testing! 🚀

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

18 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages