Projects and Environments

Everything in Proofarc is organized under projects. Each project has environments, and each environment has targets — the APIs and apps you're testing.

Structure

Project (e.g., "User Management Platform")
├── Applications
│   ├── User Service API (REST_SERVICE, Spring Boot)
│   └── User Service UI (WEB_APP, React)
├── Environments
│   ├── development
│   │   ├── Target: User Service API → http://user-service:8089
│   │   └── Target: User Service UI → http://user-service-ui
│   ├── qa
│   ├── staging
│   └── production
├── API Tests (scenarios + suites)
├── UI Tests (tests + suites)
├── Security Scans
├── Performance Tests
└── Readiness Score

Creating a Project

POST /api/projects
{
  "name": "User Management Platform",
  "description": "Full-stack user management"
}

Adding Applications

Applications represent your services with their Git repos — used for readiness scoring:

POST /api/projects/{projectId}/applications
{
  "name": "User Service API",
  "applicationType": "REST_SERVICE",
  "applicationTech": "SPRING_BOOT",
  "gitUrl": "https://github.com/org/user-service.git",
  "defaultBranch": "main"
}

Application Types

Type	Description
REST_SERVICE	REST API backend
WEB_APP	Web frontend (React, Angular, Vue)
MOBILE_APP	Mobile application (Android, iOS)
GRPC	gRPC service
GRAPHQL	GraphQL API

Adding Environments

Environments are shared across projects. Link them to your project:

# Environments already exist: development(1), staging(2), production(3), qa(4)
# Link an environment to a project (environmentId goes in the path, not the body):
POST /api/projects/{projectId}/environments/{environmentId}

# Unlink:
DELETE /api/projects/{projectId}/environments/{environmentId}

Adding Targets

Targets are the actual URLs your tests hit, configured per environment:

POST /api/environments/{envId}/targets
{
  "name": "User Service API",
  "targetType": "REST_SERVICE",
  "baseUrl": "http://user-service:8089",
  "swaggerPath": "/v3/api-docs",
  "healthcheckPath": "/actuator/health",
  "appTag": "user-service"
}

Target Types

Type	Use	Fields
REST_SERVICE	API testing, security scanning	baseUrl, swaggerPath
WEB_APP	UI testing, crawler	baseUrl, homePageUrl
NETWORK	Infrastructure scanning	IP, CIDR
MOBILE_APP	Mobile testing	appPackage

Target Authentication

Configure auth on a target so all tests (API, performance, security scans) use it automatically:

PUT /api/environments/targets/{targetId}
{
  "authConfig": {
    "type": "LOGIN_ENDPOINT",
    "mode": "AUTO",
    "loginUrl": "http://user-service:8089/auth/login",
    "tokenJsonPath": "$.accessToken",
    "credentials": {
      "username": "admin",
      "password": "your-password"
    }
  }
}

Auth is shared across the entire platform:

• API scenarios use it for every step
• Performance tests authenticate each virtual user
• Security scanners (ZAP, Nikto, Nuclei, SQLMap) inject the auth header automatically

See Authentication for all supported auth types.

App Tags

The appTag field links targets across environments. When you run a scenario with appTag: "user-service", Proofarc finds the matching target in whichever environment you select.

Cross-environment scenario execution (release#144)

When executing a scenario with only an environment parameter (no explicit targetId), the runtime now finds the matching target in that environment by appTag and uses its baseUrl — even if the scenario was originally created against a different environment with a hardcoded URL. Resolution order:

1. scenario.appTag → match against env_target.appTag in the requested env
2. scenario.target.appTag (the originally bound target's tag) → same
3. scenario.target.name case-insensitive → last-resort name match
4. Fall back to the scenario's stored baseUrl

Practically: a scenario created in development against http://user-service:8089 (tagged user-service) will run against https://app.proofarc.ai/user-svc when executed in the cloud env, provided the cloud env has a target tagged user-service. No manual reconfiguration needed.

Tip: new scenarios are clearer if you use baseUrl: "{{baseUrl}}" in the YAML — the literal {{baseUrl}} is replaced at execution time by the resolved target's URL. Hardcoded URLs still work thanks to the appTag fallback, but {{baseUrl}} makes the intent explicit.

Authentication requirement override (release#126)

Each Environment can override the auth-requirement intent declared at the Application level. This handles deployments where reality differs from intent — e.g. an AUTHENTICATED app exposed openly in a dev sandbox, or a PUBLIC app behind a VPN in staging.

Env value	Meaning
(blank — inherit)	Use each linked application's authRequirement.
REQUIRED	Auth is enforced in this environment regardless of app default.
NONE	This environment is open regardless of app default.

Resolution

effectiveAuthRequirement =
    env.authRequirement (REQUIRED → AUTHENTICATED, NONE → PUBLIC) ??
    composed from linked applications' authRequirement ??
    UNKNOWN

When multiple applications share the environment and at least one declares AUTHENTICATED, the resolver picks AUTHENTICATED for safety — running an authenticated app without credentials would 401, while running a public app with credentials is harmless.

The MCP list_environments tool surfaces both:

• authRequirement — the editable override (or null = inherit)
• effectiveAuthRequirement — the resolved value (one of PUBLIC, AUTHENTICATED, UNKNOWN). Agents read this to disambiguate an empty credentialTags list.

Set the override via the Authentication override dropdown on the Environment form. See Applications & branch tracking for the app-level side of the model.

Best Practices

1. One project per service/product — not per team
2. Same target names across environments — "User Service API" in dev, qa, staging, prod
3. Use appTags consistently — enables environment switching without reconfiguring tests
4. Add swaggerPath — enables API contract coverage scoring
5. Add healthcheckPath — enables runtime health verification
6. Declare authRequirement on Applications — and override per environment only when a deployment exception exists (release#126)