Scan Project

scan-project

Scan the user's project codebase to detect all services, classify them, recommend free deployment platforms, and write three documentation files.

Step 1: Read Project Files (silently, do not prompt the user)

Read the following files in this order. Skip files that don't exist without mentioning it.

1. docker-compose.yml or docker-compose.yaml — primary source of truth for services and ports
2. All package.json files (root, then each workspace directory under apps/, packages/, etc.)
3. turbo.json — Turborepo monorepo indicator
4. pnpm-workspace.yaml — pnpm workspace indicator
5. .env.example and any *.env.example files — environment variable discovery
6. README.md — additional context and start commands
7. Makefile — start commands and task definitions
8. All Dockerfile* files — service definitions and exposed ports
9. go.mod — Go dependency detection
10. requirements.txt or pyproject.toml — Python dependency detection
11. .nvmrc, .node-version, or engines field in root package.json — Node version

Step 2: Detect and Classify Services

Apply these detection rules to everything read in Step 1.

Monorepo Detection

• turbo.json exists → Turborepo monorepo
• pnpm-workspace.yaml exists → pnpm workspace
• "workspaces" key in root package.json → npm workspace
• apps/ directory present → treat each subdirectory of apps/ as a separate deployable service
• Each app in apps/ gets its own row in all output tables

Frontend Detection (check dependencies and devDependencies in each package.json)

Backend Detection

Database Detection

Queue / Redis Detection

Cron / Worker Detection

Step 3: Write Three Output Files

Create the DEPLOYMENT_DOCS/ directory if it does not exist. Write the following three files exactly as specified. Populate all sections with real detected values — do not leave placeholder text.

DEPLOYMENT_DOCS/HOW_TO_RUN.md

# How to Run Locally

## Prerequisites
[Node version from .nvmrc / engines field, Python version, Go version, Docker if needed — only what applies]

## Install Dependencies
[Exact install commands per service, e.g., `npm install`, `pnpm install`, `pip install -r requirements.txt`]

## Environment Variables
[List every variable from .env.example with an inferred description. Format: `VAR_NAME` — description]

## Start Services (in order)
[Exact start command for each service, labeled by service name. Include any required ordering, e.g., "start DB before API".]

## Local URLs
[Service name → http://localhost:PORT for each service]

DEPLOYMENT_DOCS/SERVICES.md

# Services Map

| Service | Type | Framework | Local Port | Depends On |
|---------|------|-----------|------------|------------|
[One row per detected service. Use docker-compose ports or package.json scripts to determine local port.]

## Environment Variables Per Service
[For each service: list env vars it consumes, and where the value comes from (e.g., "from DATABASE_URL → output of Supabase/Neon setup")]

DEPLOYMENT_DOCS/DEPLOYMENT_PLAN.md

# Deployment Plan

## Detected Services
[Bulleted list: service name, type, framework]

## Recommended Platforms

| Service | Platform | Reason | Free Tier Limits |
|---------|----------|--------|-----------------|
[One row per service. Include the specific reason for the platform choice.]

## Free Tier Warnings

- **Render**: Free services spin down after 15 minutes of inactivity. Cold start on next request takes ~30 seconds.
- **Supabase**: Projects pause after 7 days of inactivity on the free tier. Un-pause manually via the dashboard.
- **Upstash**: Free tier allows 10,000 Redis commands per day.
- **Railway**: NOT truly free — only a $5 trial credit. Do not use Railway unless the user specifically requests it.
[Add MongoDB or MySQL warnings here if those databases were detected.]

## Deployment Order
1. [Database service] → [platform]
2. [Redis/queue service, if applicable] → Upstash
3. [Backend service(s)] → [platform]
4. [Frontend service(s)] → [platform]

## Required Accounts
[List only the accounts needed for THIS project's platforms. Do not list accounts for platforms not recommended.]

## Environment Variable Wiring
[For each cross-service dependency, specify: after deploying Service A, set VAR_NAME on Service B using the output URL/key from Service A. Format clearly, e.g.:]

After deploying [database]:
- Set `DATABASE_URL` on [backend service] using the connection string from [Supabase/Neon dashboard]

After deploying [backend]:
- Set `NEXT_PUBLIC_API_URL` on [frontend service] using the Render service URL

Step 4: Pause and Show Summary

After writing all three files, print exactly this block (fill in the bracketed values):

=== Project Scan Complete ===
Detected services: [comma-separated list of service names and types]
Recommended deployment: [one-sentence summary, e.g., "Frontend on Vercel, API on Render, Postgres on Neon, Redis on Upstash"]

Files written to DEPLOYMENT_DOCS/:
  ✓ HOW_TO_RUN.md
  ✓ SERVICES.md
  ✓ DEPLOYMENT_PLAN.md

Does this look correct?
- Type 'yes' to proceed to authentication setup
- Or describe any corrections needed

Do not proceed to any further steps until the user responds.

Step 5: Failure Handling

If none of the following are found — package.json, docker-compose.yml / docker-compose.yaml, Dockerfile, go.mod, requirements.txt, pyproject.toml — then do not write any files. Instead, list exactly what was checked:

No project structure detected. I checked for:
- package.json (not found)
- docker-compose.yml / docker-compose.yaml (not found)
- Dockerfile / Dockerfile.* (not found)
- go.mod (not found)
- requirements.txt / pyproject.toml (not found)

Please confirm the project directory or point me to the relevant files.