Cursor gen'd arch doc

docs/ARCHITECTURE.md

@@ -0,0 +1,202 @@
+# Heroku AppLink CLI Plugin Architecture
+
+## Overview
+
+The `@heroku-cli/plugin-applink` is a Heroku CLI plugin that facilitates connections between Heroku applications and external systems, specifically Salesforce Orgs and Data Cloud Orgs. The plugin provides a comprehensive set of commands for managing authorizations, connections, and data integrations.
+
+## Project Information
+
+- **Name**: @heroku-cli/plugin-applink
+- **Version**: 1.0.1
+- **Author**: Heroku
+- **License**: Apache-2.0
+- **Node.js Version**: >= 20
+
+## Technical Stack
+
+### Core Dependencies
+- **oclif**: CLI framework for building command-line applications
+- **@heroku-cli/command**: Heroku CLI command framework
+- **@heroku-cli/color**: Color utilities for CLI output
+- **@heroku-cli/schema**: Heroku API schema definitions
+- **axios**: HTTP client for API requests
+- **adm-zip**: ZIP file handling for publishing operations
+- **open**: Browser opening utility for OAuth flows
+
+### Development Dependencies
+- **TypeScript**: Primary development language
+- **Mocha**: Testing framework
+- **NYC**: Code coverage tool
+- **ESLint**: Code linting and formatting
+
+## Architecture Components
+
+### 1. Base Command Class (`src/lib/base.ts`)
+
+The foundation of all commands, providing:
+- **AppLink API Client Configuration**: Manages connection to the AppLink service
+- **Add-on Resolution**: Handles multiple AppLink add-ons per app
+- **Authentication**: Manages SSO tokens and authorization headers
+- **Error Handling**: Standardized error messages and exit codes
+
+Key features:
+- Automatic add-on discovery and validation
+- SSO token management with base64 encoding
+- Custom API client configuration with proper headers
+
+### 2. Type System (`src/lib/applink/types.ts` & `src/lib/types.ts`)
+
+Comprehensive TypeScript definitions for:
+- **Connection Types**: `SalesforceConnection`, `DataCloudConnection`
+- **Organization Models**: `BaseOrg`, `AuthorizationOrg`, `ConnectionOrg`
+- **Status Enums**: Connection and authorization status tracking
+- **API Response Models**: `AppPublish`, `DataActionTargetCreate`, `Publication`
+
+### 3. Utilities (`src/lib/helpers.ts`)
+
+Helper functions for:
+- **Text Formatting**: `humanize()` function for user-friendly text display
+- **Object Transformation**: `humanizeKeys()` for converting API responses
+
+## CLI Commands Reference
+
+See [Commands](https://github.com/heroku/heroku-cli-plugin-applink/blob/cwall/arch-doc/README.md#commands).
+
+## Data Flow Architecture
+
+### Authentication Flow
+1. **Add-on Validation**: Verify AppLink add-on exists and is provisioned
+2. **SSO Token Retrieval**: Get add-on SSO token from Heroku API
+3. **API Client Configuration**: Set up authenticated client with proper headers
+4. **Request Authorization**: Use Bearer token for all AppLink API calls
+
+### Connection Flow
+1. **OAuth Initiation**: Create connection request and get redirect URI
+2. **Browser Opening**: Launch OAuth flow in user's browser
+3. **Status Polling**: Monitor connection status with 5-second intervals
+4. **Completion Handling**: Display success/failure status
+
+### Publishing Flow
+1. **File Validation**: Verify OpenAPI specification format
+2. **Metadata Collection**: Gather additional metadata files if specified
+3. **ZIP Archive Creation**: Package all files for upload
+4. **Multipart Upload**: Send files to Salesforce via AppLink API
+5. **Status Feedback**: Report publishing success/failure
+
+## External Integrations
+
+### Heroku Platform API
+- App information retrieval
+- Add-on management and validation
+- Configuration variable access
+- SSO token generation
+
+### AppLink Service API
+- Primary backend service for all operations
+- RESTful API with JWT authentication
+- Real-time status updates
+- File upload capabilities
+
+### Salesforce/Data Cloud APIs
+- OAuth authentication flows
+- Metadata deployment
+- Connection validation
+- API specification publishing
+
+## Error Handling Strategy
+
+### Validation Errors
+- Add-on existence and provisioning status
+- Connection name format validation
+- File format verification
+
+### Network Errors
+- Retry logic for transient failures
+- Detailed error messages with troubleshooting steps
+- Graceful degradation for offline scenarios
+
+### User Experience
+- Colored output for status indication
+- Progress indicators for long-running operations
+- Confirmation prompts for destructive operations
+
+## Testing Strategy
+
+### Unit Tests
+- Command parsing and validation
+- Error handling scenarios
+- Mock external API calls
+
+### Integration Tests
+- End-to-end command execution
+- API client configuration
+- File handling operations
+
+### Coverage
+- NYC for code coverage tracking
+- Mocha for test execution
+- Nock for HTTP mocking
+
+## Project Structure
+
+```
+src/
+├── commands/                 # CLI commands organized by topic
+│   ├── applink/             # General AppLink commands
+│   │   ├── authorizations/  # Authorization management
+│   │   └── connections/     # Connection management
+│   ├── salesforce/          # Salesforce-specific commands
+│   │   ├── authorizations/  # SF authorization management
+│   │   └── connect/         # SF connection commands
+│   └── datacloud/           # Data Cloud commands
+│       ├── authorizations/  # DC authorization management
+│       └── data-action-target/ # DC data action targets
+├── lib/                     # Shared libraries
+│   ├── applink/            # AppLink-specific types and utilities
+│   ├── base.ts             # Base command class
+│   ├── types.ts            # Global type definitions
+│   ├── helpers.ts          # Utility functions
+│   └── confirmCommand.ts   # Confirmation dialog utilities
+└── index.ts                # Plugin entry point
+
+test/                        # Test files mirroring src structure
+├── commands/               # Command tests
+├── lib/                    # Library tests
+└── helpers/                # Test utilities
+
+dist/                       # Compiled TypeScript output
+```
+
+## Build and Development
+
+### Scripts
+- `yarn build` - Compile TypeScript and generate manifest
+- `yarn test` - Run test suite with coverage
+- `yarn lint` - ESLint code checking
+- `yarn version` - Update version and regenerate README
+
+### Configuration Files
+- `tsconfig.json` - TypeScript compilation settings
+- `.eslintrc.json` - Code style and quality rules
+- `.mocharc.json` - Test runner configuration
+- `.nycrc.json` - Coverage reporting settings
+
+## Plugin Installation and Usage
+
+### Installation
+```bash
+heroku plugins:install @heroku-cli/plugin-applink
+```
+
+### Prerequisites
+- Heroku CLI installed
+- AppLink add-on provisioned on target app
+- Valid Heroku app with appropriate permissions
+
+### Basic Workflow
+1. Install AppLink add-on: `heroku addons:create heroku-applink -a <app>`
+2. Add authorization: `heroku salesforce:authorizations:add <dev_name> -a <app>`
+3. Create connection: `heroku salesforce:connect <connection_name> -a <app>`
+4. Publish API: `heroku salesforce:publish <spec_file> -a <app> -c <client> --connection-name <name>`
+
+This architecture provides a robust, extensible foundation for managing Heroku-to-external-system integrations with comprehensive CLI tooling.