API development

Pinchana API development happens inside independent Git submodules. The parent pinchana-api repository is orchestration/configuration, not one root Python package.

Clone correctly

git clone --recurse-submodules https://github.com/Pinchana/pinchana-api.git
cd pinchana-api

If you already cloned without submodules:

git submodule sync --recursive
git submodule update --init --recursive

Work inside a service

For a scraper or gateway package:

cd pinchana-inst
uv sync --frozen
uv run uvicorn pinchana_inst.main:app --host 0.0.0.0 --port 8082 --reload

Other packages follow the same pinchana_<name>.main:app convention where they expose FastAPI.

pinchana-core is a local path dependency used by services, so keep the parent/submodule checkout coherent when resolving locks or running tests.

Development Compose

For integration testing across services without production VPN credentials:

docker compose --env-file .env -f docker-compose.dev.yml up --detach --build

The development stack uses bridge networking, service DNS endpoints, direct ports, and VPN_ENABLED=false. It is intentionally different from production’s shared Gluetun namespace.

Tests

Run tests from the submodule that owns them:

cd pinchana-server
uv sync --frozen
uv run pytest -q

cd pinchana-inst
uv sync --frozen
uv run pytest -q

Some scraper repositories have opt-in live tests controlled by repository-specific environment variables. Keep live test URLs/credentials outside source control.

For a module without broad test coverage, at minimum validate its import/startup and the affected request path. Do not invent a root-wide formatter/linter command that the repository does not define.

Docker builds

Build from the parent repo root because service Dockerfiles copy both the target submodule and pinchana-core:

docker build -f pinchana-inst/Dockerfile -t pinchana-inst .

Running docker build . from inside the submodule can omit required local path dependencies.

Adding or changing a module

A new production module requires coordinated changes:

1. Public pinchana-<name> repository/submodule with package and Dockerfile.
2. Route patterns/container metadata in config/modules.yaml.
3. Production and development Compose services/networking.
4. .env.example image/port/endpoint/container variables.
5. Docker publishing workflow detection/build mapping.
6. Gateway schema/adapter changes only when the normalized v1 contract truly needs them.
7. Documentation/platform matrix updates.

Avoid leaking platform-specific response shapes into new clients; adapt module output into the shared API v1 schema.

Git submodule discipline

Normal feature work:

1. Commit and push the submodule change first.
2. From the parent repository, stage the updated submodule pointer.
3. Commit/push the parent pointer alongside any parent config changes.

A parent commit must not point to an unreachable local-only submodule SHA.

Version releases are different: the current scripts/version.py release flow automates version updates, submodule commits/pushes, parent pointer commit/push, and optional release publication. See Operations and releases rather than manually reproducing the old version-bump sequence.