# Telegram Task Earning

## Phase 05 — Core Application Foundation Report

| Field                     | Result                                     |
| ------------------------- | ------------------------------------------ |
| Status                    | **Complete**                               |
| Completed                 | 2026-09-03                                 |
| Project version           | `0.5.0`                                    |
| Web framework             | Express 5                                  |
| Runtime entry             | `server.js`                                |
| Lifecycle states          | starting, ready, draining, failed, stopped |
| Public foundation routes  | 8                                          |
| HTTP request timeout      | 30 seconds                                 |
| Graceful shutdown timeout | Environment controlled                     |
| Automated tests           | 61 passed                                  |
| Required project layout   | 77 directories / 110 files                 |
| npm scripts               | 34                                         |
| Dependency audit          | 0 vulnerabilities                          |

## Outcome

Phase 5 turns the validated configuration and MySQL foundation into a bootable, observable, and fail-closed Express web process. It intentionally exposes only service metadata, liveness, and readiness while future authentication and business modules remain unavailable.

## Startup integrity

- Environment validation occurs before resource creation.
- MySQL connectivity, supported Oracle MySQL version, UTC session time, and strict SQL mode are verified before the server becomes ready.
- The HTTP listener is established before lifecycle readiness is published.
- Partial startup closes the MySQL pool and emits a redacted fatal event.
- Runtime information comes from `package.json`, avoiding a separate manual version value.

## Request and error integrity

- A valid upstream request ID is preserved; invalid or missing values are replaced with a cryptographically random UUID.
- Every response and request log carries the correlation ID.
- Logs omit query strings, bodies, cookies, authorization values, and other secrets.
- Operational errors have stable codes and HTTP statuses.
- Unknown errors always return a generic `INTERNAL_ERROR` envelope.
- Stack traces and dependency messages never reach clients.
- Express 5 rejected async handlers flow into the central error middleware.
- Unknown routes return a consistent JSON 404 response without echoing the requested path.

## Health and lifecycle integrity

- Liveness measures the web process and does not restart an otherwise healthy process during a transient database failure.
- Readiness requires both the `ready` lifecycle state and a successful database probe.
- Concurrent readiness checks share one in-flight query and successful/failed results are briefly cached to limit probe amplification.
- Draining immediately removes the instance from readiness while liveness remains positive until shutdown completes.
- Health payloads are non-cacheable and expose no infrastructure identifiers.

## Shutdown integrity

Signal handling is registered only after startup succeeds. Shutdown is idempotent, stops new HTTP work first, waits for active work, closes MySQL next, and applies a bounded forced-close fallback. Fatal process events use the same cleanup path and retain a failure exit code.

## Verification scope

Automated tests cover service metadata, liveness, readiness, database failure, lifecycle transitions, invalid transitions, request correlation, request logging, logger redaction, error classes, invalid JSON normalization, async error handling, secret disclosure prevention, health CLI validation, MySQL startup capability checks, partial-start cleanup, graceful shutdown order, idempotent shutdown, and deadline force-close behavior.

The final quality gate passed formatting, linting, all 61 automated tests, the complete 77-key environment contract, all Phase 4 database checks, production CSS builds, and the 77-directory/110-file required project layout. Unit, integration, and security suites also pass independently. Full and production-only dependency audits reported zero known vulnerabilities, and a clean-install dry run succeeded.

A real deployment database was not accessed because no deployment credentials were provided. Database startup behavior is verified with deterministic connection doubles; the Phase 4 schema and migration tests remain in the complete test suite.

## Deferred boundaries

Phase 6 owns Helmet, CSP, CORS, body limits, CSRF, rate limiting, maintenance/ban gates, and the remaining security middleware. Phase 7 owns Telegram authentication and bot startup. Phase 8 owns Admin authentication and RBAC. No placeholder implementation pretends those controls are active.

## Phase 6 handoff

Phase 6 can add ordered security middleware around this stable application factory without changing lifecycle, logging, error, response, or health contracts.

## Primary references

- [Express health checks and graceful shutdown](https://expressjs.com/en/advanced/healthcheck-graceful-shutdown/)
- [Express error handling](https://expressjs.com/en/guide/error-handling/)
- [Node.js HTTP server lifecycle](https://nodejs.org/api/http.html)
- [Node.js process signal events](https://nodejs.org/api/process.html#signal-events)

**Phase 5 status: COMPLETE AND VERIFIED.**