Submittal Review Assistant

AI-powered cross-referencing of construction submittals against project specifications and plan documents

An intelligent system that automatically analyzes construction submittals against project specifications and plan documents using AI, helping project managers identify compliance issues, missing requirements, and inconsistencies quickly and accurately.

✨ Key Features

• 🤖 AI-Powered Analysis - GPT-4o/mini models for intelligent cross-referencing
• 📄 Document Processing - OCR support for PDFs, images, and Excel files
• 📋 Plan Document Analysis - Compare submittals against both specs AND construction plans
• 🔐 Multi-Tenant Architecture - Company isolation with role-based access control
• 📊 Real-Time Cost Tracking - Monitor AI usage costs and set budgets
• 📧 Email Notifications - Automated alerts via Resend
• ⚡ Background Processing - Redis-based async job queue
• 🎨 Modern UI - Next.js 15 with React 19 and Tailwind CSS
• 🔍 Confidence Scoring - AI confidence levels for each finding with explanations
• 📈 Analytics Dashboard - Track reviews, costs, and compliance metrics
• 🗑️ Document Management - Upload and delete documents across all types

🚀 Quick Start

Prerequisites

Required:

• Docker and Docker Compose (v2.0+)
• Node.js 20+ (for frontend development)
• Python 3.11+ (for backend development)

Accounts Needed:

• Supabase - Authentication (free tier available)
• OpenAI - AI models (pay-as-you-go)
• Resend - Email notifications (free tier available)

🐳 Docker Setup (Recommended)

1. Clone the repository

   git clone https://github.com/jesusr04/Submittal_Review.git
   cd Submittal_Review

2. Configure environment variables

   cp .env.example .env

   Edit .env and set the following required variables:

   # Supabase (from your Supabase project settings)
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_ANON_KEY=your-anon-key
   SUPABASE_JWT_SECRET=your-jwt-secret
   
   # OpenAI (from https://platform.openai.com/api-keys)
   OPENAI_API_KEY=sk-...
   
   # Resend (from https://resend.com/api-keys)
   RESEND_API_KEY=re_...
   EMAIL_FROM_ADDRESS=noreply@yourdomain.com

3. Start all services

   docker-compose up -d

   This starts:

   • PostgreSQL database (port 5432)
   • Redis cache (port 6379)
   • MinIO storage (port 9000, console 9001)
   • Backend API (port 8000)
   • Frontend app (port 3000)

4. Run database migrations

   docker-compose exec backend alembic upgrade head

5. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Docs (Swagger): http://localhost:8000/docs
   • API Docs (ReDoc): http://localhost:8000/redoc
   • MinIO Console: http://localhost:9001 (user: minioadmin, pass: minioadmin)

💻 Local Development Setup

For active development without Docker:

Backend

cd backend

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows PowerShell
# source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Set environment variables
# Copy .env.example to .env and configure

# Run migrations
alembic upgrade head

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

Frontend

cd frontend

# Install dependencies
npm install

# Set environment variables
# Create .env.local with:
# NEXT_PUBLIC_API_URL=http://localhost:8000
# NEXT_PUBLIC_SUPABASE_URL=your-url
# NEXT_PUBLIC_SUPABASE_ANON_KEY=your-key

# Start development server
npm run dev

🐘 Database Setup

Using Docker (recommended):

# Database is automatically created by docker-compose
docker-compose exec backend alembic upgrade head

Manual PostgreSQL setup:

# Create database
createdb submittal_review

# Update .env with connection string:
# DATABASE_URL=postgresql://user:pass@localhost:5432/submittal_review

# Run migrations
cd backend
alembic upgrade head

🏗️ Architecture

Technology Stack

Backend:

• Framework: FastAPI (Python 3.11+)
• Database: PostgreSQL 15
• Cache: Redis 7
• Storage: MinIO (S3-compatible)
• AI: OpenAI GPT-4o / GPT-4o-mini
• OCR: Tesseract
• Auth: Supabase JWT

Frontend:

• Framework: Next.js 15 (React 19)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Radix UI primitives
• State: React Context + Hooks
• API Client: Axios

Infrastructure:

• CI/CD: GitHub Actions
• **Contain Development

cd backend

# Activate virtual environment
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Code quality checks
ruff check .                    # Lint
ruff format .                   # Format
mypy app --ignore-missing-imports  # Type check

# Run tests
pytest                          # All tests
pytest tests/test_api/         # API tests only
pytest tests/test_services/    # Service tests only
pytest -v --cov=app            # With coverage

# Database migrations
alembic revision --autogenerate -m "Description"  # Create migration
alembic upgrade head            # Apply migrations
alembic downgrade -1            # Rollback one migration

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

Frontend Development

cd frontend

# Code quality checks
npm run lint                   # ESLint
npm run type-check            # TypeScript
npm run format                # Prettier (if configured)

# Run tests
npm test                      # All tests
npm test -- --watch          # Watch mode
npm test -- --coverage       # With coverage

# Build
npm run build                # Production build
npm run start                # Start production server

# Start development server
npm run dev

Adding a New API Endpoint

1. Create the endpoint in backend/app/api/v1/:

   from fastapi import APIRouter, Depends
   from app.auth.dependencies import require_auth
   
   router = APIRouter()
   
   @router.get("/my-endpoint")
   async def my_endpoint(user=Depends(require_auth)):
       return {"message": "Hello"}

2. Add Pydantic schemas in backend/app/schemas/:

   from pydantic import BaseModel
   
   class MyResponse(BaseModel):
       message: str

3. Include router in backend/app/main.py:

   from app.api.v1 import my_module
   app.include_router(my_module.router, prefix="/api/v1", tags=["My Module"])

4. Add TypeScript types in frontend/lib/types.ts:

   export interface MyResponse {
     message: string;
   }

5. Add API client method in frontend/lib/api.ts:

   async getMyData(): Promise<MyResponse> {
     const { data } = await this.client.get('/my-endpoint');
     return data;
   }

6. Write tests in backend/tests/test_api/ and `frontend/tests/ │ └── layout.tsx # Root layout │ ├── components/ │ │ ├── layout/ # AppShell, navigation │ │ ├── ui/ # Reusable UI components │ │ └── analytics/ # Charts & dashboards │ ├── contexts/ # React contexts │ ├── hooks/ # Custom hooks │ ├── lib/ │ │ ├── api.ts # API client │ │ ├── types.ts # TypeScript types │ │ └── supabase.ts # Supabase client │ ├── tests/ # Jest tests (52+ tests) │ └── package.json │ ├── docs/ # Documentation │ ├── API_DOCUMENTATION.md # Comprehensive API docs │ └── USER_GUIDE.md # User manual │ ├── .github/workflows/ # CI/CD │ ├── ci.yml # Test & lint │ └── docker-build.yml # Docker images │ ├── docker-compose.yml # Development stack ├── .env.examp

✅ Completed (MVP)

• ✅ Authentication & Authorization - Supabase JWT auth with RBAC
• ✅ Multi-Tenant Architecture - Company-level data isolation
• ✅ Project Management - Create and organize projects
• ✅ Specification Management - Upload and organize spec sections
• ✅ Submittal Management - Track submittals and revisions
• ✅ File Upload & Storage - PDF, images, Excel via MinIO/S3
• ✅ Document Processing - Text extraction with PyMuPDF and pdfplumber
• ✅ OCR Processing - Tesseract OCR for scanned documents
• Authentication: Supabase JWT tokens with automatic expiration
• Authorization: Role-based access control (Admin, Project Manager, Contractor, Viewer)
• Multi-Tenancy: Company-level data isolation in database
• Input Validation: Pydantic schemas on all API endpoints
• SQL Injection Protection: SQLAlchemy ORM with parameterized queries
• File Security: Type validation, size limits, and secure storage
• CORS Configuration: Whitelist-based CORS policy
• Environment Variables: Secrets stored in .env (not committed)
• HTTPS: TLS/SSL required in production

Security Best Practices

• Never commit .env files or secrets to Git
• Rotate API keys regularly (OpenAI, Resend, database passwords)
• Use strong Supabase JWT secrets (256-bit minimum)
• Enable Supabase RLS (Row Level Security) policies
• Monitor API usage and set rate limits
• Review audit logs regularly
• Keep dependencies updated (pip-audit, npm audit)

📚 Documentation

• API Documentation - Complete API reference
• User Guide - End-user manual
• Development Tracker - Development progress
• Swagger UI - Interactive API docs (when running)
• ReDoc - Alternative API docs (when running)

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest and npm test)
5. Run linters (ruff check . and npm run lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Pull Request Guidelines

• Use the PR template
• Ensure all CI checks pass
• Include tests for new features
• Update documentation as needed
• Keep PRs focused on a single feature/fix

🐛 Troubleshooting

Backend won't start

• Check .env has all required variables
• Ensure PostgreSQL is running: docker-compose ps
• Check database connection: docker-compose logs backend
• Verify migrations are applied: docker-compose exec backend alembic current

Frontend can't connect to API

• Verify NEXT_PUBLIC_API_URL in .env.local
• Check CORS settings in backend/app/config.py
• Ensure backend is running: curl http://localhost:8000/health

AI reviews are slow/failing

• Check OpenAI API key is valid
• Monitor rate limits: GET /api/v1/reviews/costs/dashboard
• Check OpenAI status: https://status.openai.com/
• Try review_mode: "quick" for faster processing

Database migration errors

• Rollback: alembic downgrade -1
• Check alembic version: alembic current
• View migration history: alembic history
• Manual fix: Connect to database and inspect tables

File uploads failing

• Check MinIO is running: docker-compose ps minio
• Verify MinIO credentials in .env
• Check bucket exists: http://localhost:9001
• Check file size limits in backend/app/config.py

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [your-email@example.com]

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenAI - GPT-4o and GPT-4o-mini models
• Supabase - Authentication and database hosting
• FastAPI - High-performance Python web framework
• Next.js - React framework for production
• Radix UI - Accessible component primitives
• Tailwind CSS - Utility-first CSS framework

---

Built with ❤️ for the construction industrysts** - 233 backend + 52 frontend tests

• ✅ CI/CD - GitHub Actions for testing and Docker builds
• ✅ API Documentation - OpenAPI/Swagger + ReDoc

🚧 Planned (Post-MVP)

• 🚧 Visual Marking System - Document annotations with a/A marks
• 🚧 Split View - Side-by-side spec/submittal comparison
• 🚧 Human Override Workflow - Review and approve/reject AI findings
• 🚧 Advanced Analytics - Historical trends and predictive insights
• 🚧 Export Reports - CSV/Excel export of findings
• 🚧 Revision Comparison - Compare submittal revisions
• 🚧 Approval Workflows - Multi-stage approval processes
• 🚧 Webhooks - Real-time event notifications
• 🚧 Mobile App - iOS and Android apps

cd backend

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run linting
ruff check .
ruff format .

# Run tests
pytest

# Start server
uvicorn app.main:app --reload

Frontend

cd frontend

# Install dependencies
npm install

# Run linting
npm run lint

# Run type checking
npm run type-check

# Run tests
npm test

# Start development server
npm run dev

📋 Features (MVP)

• Authentication - Supabase Auth with role-based access
• Project Management - Create and organize projects
• File Upload - Upload specs and submittals (PDF, images, Excel)
• OCR Processing - Extract text from scanned documents
• AI Review - Cross-reference submittals against specifications
• Findings Display - View compliance issues with confidence scores
• Notifications - Email alerts when reviews complete

🔒 Security

• JWT-based authentication via Supabase
• Role-based access control (Admin, Project Manager, Contractor)
• Input validation on all endpoints
• Rate limiting to prevent abuse
• Secure file handling with virus scanning

📄 License

MIT License