MVP-AIEP

Full-stack web application for entrepreneurship assessment. Users complete a multi-step form (formulario) that evaluates their business, and the system generates a PDF report. Admins can manage users, business centers, and review completed forms from a protected dashboard.

Stack

• Framework: Next.js 16 (App Router, Turbopack) + React 19 + TypeScript
• Database: PostgreSQL with Prisma ORM
• Auth: NextAuth v5 (Google OAuth, Microsoft Entra ID, and a dev-only Credentials provider)
• UI: shadcn/ui + Radix UI + Tailwind CSS v4
• PDF generation: external service on Google Cloud (Cloud Functions/Workflows in data_processing/)
• Package manager: pnpm (v10) — do not use npm or yarn

Monorepo layout

/
├── apps/
│   ├── frontend/          # Next.js app (all backend logic lives here, under app/api)
│   │   ├── app/
│   │   │   ├── admin/         # Admin dashboard (auth-protected)
│   │   │   ├── api/           # API routes (formularios, admin)
│   │   │   ├── formulario/    # Public multi-step form
│   │   │   └── components/    # Shared UI components (shadcn/ui)
│   │   ├── lib/            # Server utilities (Prisma, auth, scoring)
│   │   ├── auth.ts         # NextAuth configuration
│   │   └── middleware.ts   # Protects /admin/* routes
│   └── backend/            # Placeholder for a future standalone backend service
├── data_processing/        # Python scripts for document/PDF generation and parsing (Cloud Functions)
├── prisma/
│   ├── schema.prisma        # Database schema
│   └── migrations/          # Migration history
└── scripts/
    └── addAdmin.ts           # CLI to seed admin users

Prerequisites

• Node.js 22+
• pnpm 10+
• PostgreSQL (or Docker, see below)

Setup

1. Clone the repository and install dependencies:

   pnpm install

2. Create a .env file in the repo root with the following variables:

   DATABASE_URL=                          # PostgreSQL connection string
   AUTH_SECRET=                           # NextAuth secret
   NEXTAUTH_URL=                          # Base app URL (e.g. http://localhost:3000)
   AUTH_GOOGLE_ID=
   AUTH_GOOGLE_SECRET=
   AUTH_MICROSOFT_ENTRA_ID_ID=
   AUTH_MICROSOFT_ENTRA_ID_SECRET=
   AUTH_MICROSOFT_ENTRA_ID_TENANT_ID=
   ADMIN_SECRET_KEY=                      # Bearer token for the /api/admin/create endpoint

3. Apply migrations and generate the Prisma client:

   npx prisma migrate dev
   npx prisma generate

Development

pnpm dev                  # Dev server (Turbopack) on localhost:3000
pnpm dev:frontend         # Dev server with Webpack (fallback)
pnpm build                # Production build
pnpm start                # Serve the production build
pnpm lint                 # ESLint on apps/frontend
pnpm lint:fix             # ESLint with auto-fix
pnpm prettier             # Format all files

Database

pnpm db:deploy             # Run pending Prisma migrations (production)
npx prisma migrate dev     # Create and apply a new migration (development)
npx prisma generate        # Regenerate the Prisma client after schema changes
npx prisma studio          # Visual database browser

Docker

Run the app alongside a PostgreSQL instance:

pnpm docker:build
pnpm docker:up
pnpm docker:down

Admin management

npx tsx scripts/addAdmin.ts email@example.com "Name" [SUPER_ADMIN|ADMIN_CENTRO]

Architecture

Data model

• Admin — authenticated dashboard users with a Role (SUPER_ADMIN / ADMIN_CENTRO / ADMIN_READONLY), optionally scoped to a Centro
• Centro — business center, linked to Comunas via CentroComunaRelation
• Formulario — form template (global or centro-specific), can be active/inactive
• Usuario — end-user who fills out the form
• Informe — submission result linking Usuario + Centro + Formulario, storing JSON answers and scores

Auth flow

NextAuth v5 with JWT sessions. Middleware protects /admin/* and redirects unauthenticated users to /admin/access. On sign-in, validateAdmin checks the database for an active Admin record matching the email; role and centroId are embedded in the JWT token. Role-based access is enforced in apps/frontend/app/admin/(protected)/layout.tsx.

Form (formulario) engine

Form questions and sections are defined statically in apps/frontend/app/formulario/constants.ts (SECTIONS: FormSection[]). Questions support types single (with options), text, and input, and support conditional visibility via showIf. The submission endpoint (/api/formularios) assigns a Centro based on the user's region/comuna, then calls an external Google Cloud service to generate the PDF report.

Deployment

Production deployment is automated via GitHub Actions (.github/workflows/deploy.yml) on every push to main: it builds the Docker image, runs Prisma migrations against Cloud SQL, and deploys to Google Cloud Run.

License

MIT — see LICENSE.