CoreAPI — FTP-to-HTTPS migration and operations platform

03 · Architecture

System at a glance

Stack

• Node.js
• Express
• MySQL
• Redis
• Docker Compose
• Nginx
• Zod
• Pino
• React
• Vite

04 · Decisions

Engineering decisions

Each decision is written as the constraint that forced it, the choice made, the cost accepted, and what it bought.

• D01

  Migrate client by client, not on a single cut-over day

  Constraint

  The installed desktop clients could not all be updated at once, and a failed switch would cut a client off from its back office.

  Decision

  Let each client provision itself with the FTP credentials it already had, track every client as FTP, dual or API, and mirror new settings back into the plain-text files that FTP-era clients still read.

  Trade-off

  Two protocols and a compatibility bridge had to stay running and consistent for the whole migration, and the bridge is extra code to retire afterwards.

  Result

  Clients moved in growing batches with no service-wide cut-over, and problems surfaced on a small group before they could reach everyone.

• D02

  Nothing listens publicly except the edge

  Constraint

  The API runs on the same server as a public web server, and the database, cache and admin tools must never face the internet.

  Decision

  Bind every published container port to loopback, place Nginx between the TLS edge and the API, and keep MySQL, Redis and the admin portal on a private container network.

  Trade-off

  Administrators need an SSH tunnel to reach the portal, and troubleshooting starts on the host.

  Result

  The public attack surface is a single HTTPS entry point; data stores and operations tooling are unreachable from outside.

• D03

  Operations without handing out the Docker socket

  Constraint

  The portal needs container status, logs and restarts, but raw access to the Docker socket is equivalent to root on the host.

  Decision

  Route Docker calls through a socket proxy that exposes only container and info endpoints — exec, images, volumes and build stay disabled — and permit only named service/action pairs, with typed confirmation for disruptive actions and an operations audit log.

  Trade-off

  Every new operational action needs an explicit allowlist entry and a review, which slows down ad-hoc fixes.

  Result

  Operators can diagnose and restart services from the portal without the portal becoming a path to host takeover.

• D04

  Rate limits follow the caller's role

  Constraint

  Desktop clients, service staff and super-admins have very different legitimate request volumes, and provisioning is an obvious abuse target.

  Decision

  Sliding-window limits in Redis sorted sets, keyed per authenticated user with a budget per role, plus a separate hourly per-IP limit on provisioning. Refusals include a Retry-After header.

  Trade-off

  Every authenticated request pays an extra Redis round trip, and Redis becomes part of the request path.

  Result

  One noisy client cannot exhaust capacity for everyone else, and well-behaved clients are told when to retry.

• D05

  Resumable uploads, strict filenames

  Constraint

  Replacing FTP meant large files over unreliable connections, with filenames arriving from many desktop installations — including Arabic script.

  Decision

  Chunked uploads tracked by upload ID, with a status endpoint that reports received and missing chunks and a scheduled sweep for abandoned uploads. Filenames are rejected — never silently rewritten — when they contain control characters, path separators, a leading dot or characters outside a whitelist.

  Trade-off

  Rejecting instead of sanitizing means some legacy filenames must be renamed on the client.

  Result

  Interrupted transfers resume instead of restarting, and path-traversal attempts never reach the filesystem layer.