sanketsaurav/pnrapi

1. Repository shape

- This is a small, single-purpose Python API service for Indian Railways PNR status lookup.

- There is no multi-service backend, no database, and no frontend. The architecture is basically one HTTP entrypoint plus a few support files.

2. Public API boundary

- The service exposes one main route: GET /pnr/<pnr>.

- The input is a 10-digit PNR number.

- The output is a JSON payload with a top-level status field and a data object containing train, route, and passenger status details.

3. Request handling layer

- api.py is the application entrypoint and likely contains the web route/controller logic.

- Its job is to accept the PNR request, decide whether to serve a dummy/test response or query live data, and return the final JSON response.

4. External data dependency

- The core business function depends on an upstream Indian Railways PNR information source.

- This repo acts as a proxy/adapter over that external system, normalizing whatever raw response it gets into a stable JSON contract for callers.

5. Transformation and normalization

- utils.py appears to hold helper logic for parsing, cleaning, or reshaping fetched PNR data.

- The README’s sample response suggests the service converts upstream data into a consistent structure with fields like train number, train name, travel date, boarding/alighting stations, class, and passenger status.

6. Station metadata boundary

- station_codes.json is a local lookup table for station code-to-name mapping.

- This indicates a normalization step in the response pipeline: raw station codes from upstream are resolved into human-readable station names before returning JSON.

7. Test/dummy response path

- dummy_response.json is a fixture used for testing and development.

- The README explicitly documents PNR 0123456789 as a special test input that returns this dummy payload, which means the service has a deterministic offline/fixture branch separate from live lookups.

8. Configuration

- settings.py likely contains runtime configuration such as upstream URLs, timeouts, environment-specific toggles, or constants used by the request pipeline.

- This separates deploy-time settings from request-handling code.

9. Deployment/runtime

- Procfile suggests the service is designed to run on a process manager / PaaS-style host using a web worker command.

- requirements.txt defines the Python runtime dependencies for the API and any scraping/parsing libraries it relies on.

10. Response contract

- The API always returns a status plus a structured data payload.

- Notable result states documented in the README are:

- OK for successful lookups

- PNR FLUSHED / SERVICE UNAVAILABLE when the PNR is unavailable or upstream is down

- ERROR for unexpected fetch/parse failures

- This makes the service a stable adapter around an unreliable upstream source.

11. Data flow summary

- Client sends PNR request → api.py handles route → helper/config/lookup files enrich or normalize the request → upstream PNR source is queried or dummy_response.json is returned → response is transformed into the documented JSON schema → JSON is sent back to the client.

12. Architectural takeaway

- The repo is best diagrammed as a thin API façade over an external rail PNR source, with local support files for configuration, station metadata, and deterministic test fixtures.