Configuration Reference
Reference for the repository’s current environment variables, config files, hardcoded runtime settings, and workflow gates across the web, API, and AI services.
Overview
This repository currently relies far more on static configuration than on environment-driven configuration. The inspected implementation does not define any .env files, does not read application environment variables in source code, and does not implement an app-level feature flag system.
This page reflects the current implementation in the repository, not an intended future configuration model. If a setting is listed here, it was found in source files, Dockerfiles, package scripts, or GitHub Actions workflows.
Use this page to answer three practical questions:
- Which settings affect local runtime, builds, and deployment
- Where each setting is defined
- Which mismatches in the current configuration can affect development or container runtime
Configuration surface summary
Configuration is spread across a small number of concrete surfaces rather than a centralized settings layer.
- Application runtime code defines hardcoded behavior such as the API port, API CORS origin, and the AI service health route.
- Package scripts define dev and build commands for the monorepo and individual apps.
- Static config files define TypeScript, workspace, Turbo, Nest, and Python tool settings.
- Dockerfiles define container base images, exposed ports, commands, and one runtime environment variable for the AI service image.
- GitHub Actions workflows define service names, image names, branch filters, concurrency behavior, setup versions, and release gating logic.
The repository does not currently expose a general configuration abstraction for ports, CORS origin, or deployment behavior. Several values that are often environment-driven in other projects are fixed directly in code or workflow files.
Environment variables
App environment variables
The inspected source code does not consume repository-defined application environment variables.
No .env files were found in the repository tree, and no application code reads of process.env, import.meta.env, os.getenv, getenv, or dotenv were found.
Current status
Purpose: Configure application runtime through repository-defined environment variables.
Type: none.
Explicit value: not present.
Required: No. The current codebase does not depend on a repo-defined .env file for local startup.
Purpose: Load local configuration from .env files.
Type: none.
Explicit value: not implemented.
Required: No. No .env, .env.example, or application dotenv loading was found.
Workflow and container environment variables
The repository does use environment variables outside application code in Docker and GitHub Actions.
Docker runtime environment
Purpose: Prepend the AI service virtual environment binary path so uvicorn and installed tools resolve from /app/.venv/bin.
Type: string.
Explicit value: /app/.venv/bin:$PATH.
Required: No. The AI service Docker image sets this value internally.
GitHub Actions workflow environment
Purpose: Identify the service being built in a workflow.
Type: string.
Explicit values: api, web, and ai-service, depending on the workflow file.
Required: Yes for the current workflow implementation, because each workflow sets it explicitly.
Purpose: Define the Docker image name used by a workflow.
Type: string.
Explicit values: gravity-api, gravity-web, and gravity-ai-service.
Required: Yes for the current workflow implementation, because each workflow sets it explicitly.
Purpose: Authenticate Docker login in GitHub Actions.
Type: string.
Explicit value: GitHub-provided secret at workflow runtime.
Required: Yes for workflow execution paths that log in to GitHub Container Registry.
Purpose: Drive branch-based and event-based workflow behavior.
Type: GitHub Actions context values.
Explicit values: github.ref, github.ref_name, github.actor, github.repository_owner, and github.event_name.
Required: Yes for the current workflow conditions and tagging logic.
Grounded excerpts
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]
env:
SERVICE_NAME: api
IMAGE_NAME: gravity-api
Application runtime settings
Application runtime behavior is mostly fixed in source rather than configured dynamically.
API service runtime settings
The API bootstrap file hardcodes both network binding and CORS behavior.
const app = await NestFactory.create(AppModule);
app.enableCors({
origin: ["http://localhost:3000"],
credentials: true,
});
await app.listen(3001);
// Effective runtime behavior:
// - CORS allows exactly http://localhost:3000
// - Credentialed requests are enabled
// - API listens on port 3001
// - No environment-based override is present
Purpose: Define which frontend origins may access the API through CORS.
Type: array of strings.
Explicit value: ["http://localhost:3000"].
Required: Yes. The current bootstrap code passes this value directly to app.enableCors(...).
Purpose: Allow credentialed cross-origin requests.
Type: boolean.
Explicit value: true.
Required: Yes. The current bootstrap code sets it directly.
Purpose: Define the API listening port.
Type: number.
Explicit value: 3001.
Required: Yes. The service binds with app.listen(3001) and does not read a port from environment variables.
AI service runtime settings
The AI service runtime surface is small and mostly script- and Docker-defined.
@app.get("/health")
def health():
return {"status": "ok"}
{
"scripts": {
"dev": "uv run uvicorn main:app --reload --port 8001"
}
}
Purpose: Expose a health check endpoint for the AI service.
Type: string.
Explicit value: /health.
Required: Yes. The route is defined directly in application code.
Purpose: Define the AI service port during local development.
Type: number.
Explicit value: 8001.
Required: Yes for the current dev script, because the script passes --port 8001.
Purpose: Define the AI service port in the container entry command.
Type: number.
Explicit value: 8001.
Required: Yes for the current Docker runtime, because the container command passes --port 8001.
Web service runtime notes
The web app runtime port is not driven by a repository-defined environment variable. The inspected repository instead documents and hardcodes port expectations in multiple places, including 3000 in Docker and root documentation, with a separate development note referencing 5173.
Config files
These files define the monorepo’s build, toolchain, and service-level behavior. The entries below focus on settings that materially affect runtime, builds, or deployment.
Root package and workspace configuration
Purpose: Pin the package manager and version for the repository.
Type: string.
Explicit value: pnpm@10.13.1.
Required: Yes for consistent dependency installation and workspace behavior.
Purpose: Start the repository development workflow from the root package.
Type: package script.
Explicit value: present in package.json.
Required: No. It is a convenience entrypoint rather than a runtime requirement.
Purpose: Start the web app development flow from the root package.
Type: package script.
Explicit value: present in package.json.
Required: No.
Purpose: Start the API development flow from the root package.
Type: package script.
Explicit value: present in package.json.
Required: No.
Purpose: Start the AI service development flow from the root package.
Type: package script.
Explicit value: uv run uvicorn main:app --reload --port 8001.
Required: No, but it is the current scripted AI service dev entrypoint.
Purpose: Define workspace package globs for pnpm.
Type: array of strings.
Explicit value: ["apps/*", "packages/*"].
Required: Yes for workspace resolution.
Purpose: Exclude selected built dependencies from pnpm handling.
Type: array of strings.
Explicit value: ["esbuild"].
Required: No.
Turbo configuration
Purpose: Disable caching for development tasks.
Type: boolean.
Explicit value: false.
Required: Yes for the current Turbo task definition.
Purpose: Define upstream build dependencies.
Type: array of strings.
Explicit value: ["^build"].
Required: Yes for the current build graph.
Purpose: Declare build output paths for caching and orchestration.
Type: array of strings.
Explicit value: ["dist/**"].
Required: Yes for the current build task definition.
API service config files
Purpose: Configure Nest CLI monorepo mode.
Type: boolean.
Explicit value: false.
Required: Yes in apps/api/nest-cli.json.
Purpose: Define the API source root for Nest CLI operations.
Type: string.
Explicit value: src.
Required: Yes.
Purpose: Define the Nest bootstrap entry file name.
Type: string.
Explicit value: main.
Required: Yes.
Purpose: Control automatic spec file generation.
Type: boolean.
Explicit value: false.
Required: Yes in the current Nest CLI config.
Purpose: Control manual restart behavior in Nest CLI.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Point Nest CLI to the build TypeScript config.
Type: string.
Explicit value: ./tsconfig.build.json.
Required: Yes.
Purpose: Disable webpack-based compilation in Nest CLI.
Type: boolean.
Explicit value: false.
Required: Yes.
Purpose: Remove the output directory before rebuilding.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Define the API TypeScript output target.
Type: string.
Explicit value: ES2024 in apps/api/tsconfig.json.
Required: Yes.
Purpose: Define the API TypeScript module format.
Type: string.
Explicit value: ESNext in apps/api/tsconfig.json.
Required: Yes.
Purpose: Define TypeScript module resolution behavior.
Type: string.
Explicit value: Bundler in apps/api/tsconfig.json.
Required: Yes.
Purpose: Define the API build output directory.
Type: string.
Explicit value: ./dist.
Required: Yes.
Purpose: Enforce null-safety checks in the API TypeScript build.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Enable incremental TypeScript compilation.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Generate source maps for the API build.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Exclude test and build artifacts from the API build config.
Type: array of strings.
Explicit value: ["node_modules", "test", "dist", "**/*spec.ts"].
Required: Yes in apps/api/tsconfig.build.json.
Web config files
Purpose: Build the web app.
Type: package script.
Explicit value: remix vite:build.
Required: Yes for the current web build flow.
Purpose: Start the web development server.
Type: package script.
Explicit value: remix vite:dev.
Required: No.
Purpose: Start the production web server from the build output.
Type: package script.
Explicit value: remix-serve ./build/server/index.js.
Required: Yes for the current container start behavior.
Purpose: Define Vite plugins for the web app.
Type: array.
Explicit value: tailwindcss(), remix(), and tsconfigPaths().
Required: Yes for the current web build configuration.
Purpose: Define JSX transform behavior for the web app TypeScript config.
Type: string.
Explicit value: react-jsx.
Required: Yes.
Purpose: Disable file emission in the web TypeScript config.
Type: boolean.
Explicit value: true.
Required: Yes.
Shared TypeScript base config
Purpose: Define the shared TypeScript standard libraries.
Type: array of strings.
Explicit value: ["ES2022", "DOM"].
Required: Yes in tsconfig.base.json.
Purpose: Enable shared strict TypeScript checking.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Allow importing JSON modules in shared TypeScript settings.
Type: boolean.
Explicit value: true.
Required: Yes.
AI service config files
Purpose: Pin the local Python version for the AI service.
Type: string.
Explicit value: 3.14.
Required: Yes in apps/ai-service/.python-version.
Purpose: Define the supported Python runtime range for the AI service.
Type: string.
Explicit value: >=3.14.
Required: Yes in apps/ai-service/pyproject.toml.
Purpose: Define the Python runtime dependencies for the AI service.
Type: array of strings.
Explicit value: fastapi, pydantic, and uvicorn.
Required: Yes.
Dockerfiles
FROM node:20-alpine
EXPOSE 3000
CMD ["npm", "run", "start"]
FROM oven/bun:1-alpine
EXPOSE 3000
CMD ["bun", "run", "start:prod"]
FROM python:3.14-slim
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8001
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]
Purpose: Define the base image for the web container build.
Type: string.
Explicit value: node:20-alpine.
Required: Yes.
Purpose: Declare the web container port.
Type: number.
Explicit value: 3000.
Required: Yes in apps/web/Dockerfile.
Purpose: Define the base image for the API container build.
Type: string.
Explicit value: oven/bun:1-alpine.
Required: Yes.
Purpose: Declare the API container port.
Type: number.
Explicit value: 3000.
Required: Yes in apps/api/Dockerfile.
Purpose: Define the runtime base image for the AI service container.
Type: string.
Explicit value: python:3.14-slim.
Required: Yes.
Purpose: Define the image source used for uv in the AI service Docker build.
Type: string.
Explicit value: ghcr.io/astral-sh/uv:latest.
Required: Yes in the current Dockerfile.
Purpose: Declare the AI service container port.
Type: number.
Explicit value: 8001.
Required: Yes.
Workflow and build configuration
GitHub Actions workflows provide the repository’s main deployment-time configuration layer.
Branch and environment gates
Purpose: Restrict workflow execution to selected branches.
Type: array of strings.
Explicit value: ["main", "dev"].
Required: Yes in the current workflow definitions.
Purpose: Select the deployment environment from the branch name.
Type: branch-to-environment rule.
Explicit value: main maps to production, all other current matched branches map to development.
Required: Yes for current deployment targeting.
Purpose: Limit service workflows to relevant file changes.
Type: hardcoded path filters.
Explicit value: defined separately per service workflow.
Required: Yes in the current CI setup.
Image naming and version setup
Purpose: Name the API container image in CI.
Type: string.
Explicit value: gravity-api.
Required: Yes.
Purpose: Name the web container image in CI.
Type: string.
Explicit value: gravity-web.
Required: Yes.
Purpose: Name the AI service container image in CI.
Type: string.
Explicit value: gravity-ai-service.
Required: Yes.
Purpose: Define the Node version used in workflows.
Type: string.
Explicit value: 20.
Required: Yes in current CI setup.
Purpose: Define the pnpm version used in workflows.
Type: string.
Explicit value: 10.13.1.
Required: Yes.
Purpose: Define the Bun version used in workflows.
Type: string.
Explicit value: latest.
Required: Yes where Bun is installed in CI.
Purpose: Define the uv version used in workflows.
Type: string.
Explicit value: latest.
Required: Yes where the AI service workflow installs uv.
Concurrency and release gates
Purpose: Prevent overlapping workflow runs for the same ref.
Type: string pattern.
Explicit values: api-${github.ref}, web-${github.ref}, and ai-service-${github.ref}.
Required: Yes.
Purpose: Cancel earlier runs when a new run starts for the same concurrency group.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Derive semantic version bump level from commit messages.
Type: conditional rules.
Explicit value: major for [major] or BREAKING CHANGE, minor for [minor] or feat( or feat:, otherwise patch.
Required: Yes in the current release automation.
Purpose: Restrict the latest Docker tag to the main branch.
Type: branch condition.
Explicit value: enabled only on main.
Required: Yes in current tag logic.
Purpose: Restrict the dev-latest Docker tag to the dev branch.
Type: branch condition.
Explicit value: enabled only on dev.
Required: Yes in current tag logic.
Feature flags
No true application feature flag system was found in the inspected codebase.
Boolean settings exist in the repository, but they are not feature flags unless application code uses them to enable or disable user-facing behavior at runtime. In this repository, the booleans that were found belong to bootstrap settings, build tools, or workflows.
App code feature flags
Purpose: Toggle application behavior through a dedicated feature-flag mechanism.
Type: none.
Explicit value: not present.
Required: No. No app-level feature flag framework or env-driven toggle system was found.
Workflow and tool booleans that are not feature flags
Purpose: Allow credentialed CORS requests in the API bootstrap config.
Type: boolean.
Explicit value: true.
Required: Yes.
Purpose: Disable caching for Turbo dev tasks.
Type: boolean.
Explicit value: false.
Required: Yes.
Purpose: Cancel overlapping CI runs for the same ref.
Type: boolean.
Explicit value: true.
Required: Yes.
Notable mismatches
A few current settings conflict across files or docs and can affect local setup or deployment assumptions.
The API service listens on port 3001 in source code, but apps/api/Dockerfile exposes port 3000. Treat this as an active mismatch until one side changes.
Purpose: Highlight the difference between API source runtime port and container exposed port.
Type: mismatch.
Explicit value: source listens on 3001, Docker exposes 3000.
Required: No, but it is operationally important.
Purpose: Highlight inconsistent frontend port expectations across repository materials.
Type: mismatch.
Explicit value: root docs and API CORS expect http://localhost:3000, while the web app README mentions http://localhost:5173.
Required: No, but it affects local integration expectations.
Purpose: Highlight the naming inconsistency for the Python or AI service.
Type: mismatch.
Explicit value: the root README refers to py-service, while the actual directory is apps/ai-service.
Required: No, but it can mislead local setup and script interpretation.
Purpose: Call out that ports, CORS origin, and several deployment choices are hardcoded rather than abstracted into application configuration.
Type: implementation characteristic.
Explicit value: present across runtime code and workflows.
Required: No, but it is important when planning changes.