How api7/adc works
Project Type & Purpose
• ADC is a CLI utility that communicates with different API backends (API7 Enterprise and Apache APISIX), offering commands such as ping, dump, diff, sync, convert, and lint.
• It also includes a converter module for OpenAPI specs, meaning the tool has a pluggable or layered design where different backend integrations and conversion modules are “plugged in.”
Breakdown of the Project Structure
• The “apps” directory contains CLI applications (the core executable logic) and end-to-end test applications (cli-e2e) which simulate real use cases.
• The “libs” directory is split into several libraries:
– backend-api7 and backend-apisix: These libraries encapsulate the logic to connect with either API7 Enterprise or Apache APISIX, respectively.
– converter-openapi: This library processes OpenAPI specifications converting them to ADC config formats.
– sdk: Contains core utilities and shared features such as differ, converter, and logging functions used by the CLI.
– tools: Likely includes additional tooling (e.g., Docker and S3 utilities) for development or deployment.
• Configuration and tool-related files (Nx configuration, ESLint, Jest, Prettier, etc.) indicate a well-structured, modular application built with best practices in mind.
Main Components
a. CLI Application Core:
– Represents the “apps/cli” codebase where user commands are parsed, and tasks (e.g., ping, dump, diff, sync, convert, lint) are executed.
– Outline how these tasks call into the SDK.
b. SDK/Shared Modules:
– Illustrate how the CLI interacts with core functionalities (found in “libs/sdk”) like resource management, logging, and generic utilities.
c. Backend Integrations:
– Two distinct modules:
▪ Backend API7 (from “libs/backend-api7”)
▪ Backend APISIX (from “libs/backend-apisix”)
– Each of these components will be responsible for handling the specific protocol, authentication, and API interactions.
d. Converter Module:
– Show “libs/converter-openapi” as a separate module that handles the conversion of OpenAPI 3 specifications into ADC configuration.
e. Testing & Validation:
– Represent the E2E tests (apps/cli-e2e) and other test folders across libraries to indicate the quality assurance process.
f. Auxiliary Tools:
Component Relationships and Data Flow
– The SDK (which aggregates core functionalities and utilities).
– The backend modules. For example, when the CLI initiates a “ping” or “sync”, it calls the respective backend module by selecting API7 Enterprise or APISIX based on the configuration.
– The converter module for “convert” commands.
• How test suites (E2E) simulate or interact with these components to validate behavior.
Architectural Patterns
• Modularity: Clearly indicate that the project follows a modular architecture by separating core CLI logic from backend specific implementations and conversion utilities.
• Plugin-like functions: Each backend integration acts almost as a “plugin” that provides specialized API interactions.
• Layered separation: Present a layered view—from CLI interface to SDK/shared modules and then to backend integrations.
• Use dependency injection (or similar design patterns) where appropriate, although not explicitly visible, it is implied by the project’s structure to support testing and extensibility.
Instructing the Principal Software Engineer
• Testing modules distinctly by labeling “E2E Tests (apps/cli-e2e)” so that quality assurance is seen as an integral part of the architecture.
Happy diagramming!