FORGEAI – Complete Existing MVP of an Engineering Decision Intelligence Platform (Next.js + FastAPI)

# Project Overview

I am building **FORGEAI – Engineering Decision Intelligence (EDI)**, a B2B software platform designed to improve engineering workflow verification, quality control, evidence traceability, and work-package readiness in industrial infrastructure projects.

The initial target use case is the **Hydro-Mechanical (H&M) department, specifically penstock fabrication and inspection workflows in pumped-storage hydropower projects**.

An initial codebase and MVP foundation already exist. I am looking for an experienced full-stack developer to review the existing code, fix bugs and integration issues, complete the core workflows, and deliver a stable, demonstrable MVP. I do not want an unnecessary complete rewrite.

## Existing Technology Stack

- Frontend: Next.js, React, TypeScript
- Backend: Python, FastAPI
- Database: SQLAlchemy with SQLite in the current development setup
- API integration: REST APIs
- Existing modules include templates, a Rules Builder, work packages, verification, and related engineering workflow functionality.

The freelancer must first inspect the existing codebase and propose a realistic implementation plan before making major architectural changes.

## Core Product Requirements

### 1. Engineering Workflow Templates
- Create and manage engineering work-package templates.
- Define workflow steps, requirements, dependencies, and required evidence.
- Support template versions and maintain consistency between templates and existing work packages.

### 2. Configurable Rules Builder
- Create, edit, and save verification rules.
- Support operators such as equals, not equals, allowed values (IN), evidence existence, and numeric ranges.
- Support references between relevant workflow steps and requirements.
- Validate rule configurations and return meaningful error messages.

### 3. Work-Package Management
- Create actual work packages using configured templates.
- Assign unique identifiers to work packages and associate them with the appropriate project.
- Track workflow progress and requirement fulfillment.
- Display the current status of each work package.

### 4. Evidence Management
- Upload and associate relevant evidence with the correct work package, step, and requirement.
- Handle inspection reports, checklists, documents, and other supported evidence types.
- Validate file types and sizes, handle upload errors, and protect access to uploaded files.
- Preserve traceability between evidence and verification decisions.

### 5. Deterministic Verification Engine
- Evaluate work packages against configured rules and evidence requirements.
- Clearly explain why a work package passes, fails, or remains blocked.
- Display missing requirements, failed rules, and actionable blockers.
- Allow re-evaluation after requirements or evidence are updated.
- Keep verification logic deterministic and testable; do not rely on an LLM to make safety-critical engineering approvals.

### 6. Decision and Blocker Dashboard
- Display work-package status, outstanding blockers, and workflow progress.
- Help users identify what must be completed before a work package can proceed.
- Provide a clear explanation of each verification result and the next required action.
- Maintain human engineering and QA/QC approval authority.

### 7. API and Frontend Integration
- Connect all existing frontend pages to the correct backend APIs.
- Fix API route mismatches, request/response schema issues, authentication problems, and navigation errors.
- Ensure loading, empty, success, and error states are handled properly.
- Remove broken or placeholder functionality from the agreed MVP scope.

### 8. Database, Security, and Reliability
- Review database models, relationships, and migrations.
- Verify authentication and authorization across protected endpoints.
- Ensure users cannot access another company's or project's restricted information.
- Secure file uploads and access to stored evidence.
- Review environment configuration, CORS, secrets management, and error handling.
- Do not commit API keys, passwords, or production secrets to source control.

### 9. Testing and Documentation
- Add or repair automated tests for critical backend functionality.
- Test rule evaluation, work-package creation, evidence submission, verification, and blocker handling.
- Provide clear local setup and deployment instructions.
- Document environment variables, API endpoints, database setup, and known limitations.
- Provide a short handover walkthrough.

## Example Real-World Workflow

A penstock fabrication work package progresses through relevant stages such as material receipt, marking and cutting, rolling, fit-up, inspection, welding, non-destructive testing, and release.

FORGEAI should evaluate the configured requirements for a work package, identify missing evidence or failed conditions, explain why the work package is blocked, and show what needs to happen next.

The workflow and acceptance criteria will be configured using approved project requirements. The software must not independently certify engineering quality or replace authorized inspections and approvals.

## Expected Deliverables

1. Review of the existing codebase and a prioritized technical assessment.
2. A working backend that starts reliably and exposes its API documentation.
3. A functioning frontend integrated with the backend.
4. Working templates, Rules Builder, work packages, evidence management, verification, and blocker workflows within the agreed scope.
5. Database setup and migrations appropriate to the existing architecture.
6. Automated tests for critical functionality.
7. Security and reliability fixes identified within the agreed scope.
8. Setup instructions, API documentation, and deployment guidance.
9. Source code changes committed to a repository controlled by me.
10. A demonstration of the completed workflows and a handover session.

## Working Arrangement

I already have an existing codebase, product direction, and initial technical implementation. I will provide access to the relevant project files after discussing the scope with shortlisted candidates.

Please do not propose a complete rewrite before reviewing the existing implementation.

I prefer milestone-based delivery, with each milestone demonstrated and reviewed before the next payment is released.

## Please Include in Your Proposal

- Your experience with Next.js, TypeScript, FastAPI, Python, SQLAlchemy, and REST API integration.
- Examples of similar full-stack applications you have developed.
- Your approach to reviewing and debugging an existing codebase.
- Your estimated timeline and milestone-wise quotation.
- Your testing, security, and handover approach.
- Any assumptions, exclusions, or additional costs.

I am looking for a practical developer who can work systematically, communicate clearly, and deliver a reliable MVP that can be tested with real industrial users.

#Priority: Complete and stabilize the existing MVP first. New AI features and advanced integrations are outside the initial scope unless separately agreed.