nevo-david_postiz/PROJECT_STRUCTURE.md

# Postiz CLI - Project Structure

## Overview

The Postiz CLI is a complete command-line interface package for interacting with the Postiz social media scheduling API. It's designed for developers and AI agents to automate social media posting.

## Directory Structure

```
apps/cli/
├── src/                          # Source code
│   ├── index.ts                  # Main CLI entry point
│   ├── api.ts                    # API client for Postiz API
│   ├── config.ts                 # Configuration and environment handling
│   └── commands/                 # Command implementations
│       ├── posts.ts              # Posts management commands
│       ├── integrations.ts       # Integrations listing
│       └── upload.ts             # Media upload command
│
├── examples/                     # Usage examples
│   └── basic-usage.sh            # Shell script example
│
├── dist/                         # Build output (generated)
│   ├── index.js                  # Compiled CLI executable
│   └── index.js.map              # Source map
│
├── package.json                  # Package configuration
├── tsconfig.json                 # TypeScript configuration
├── tsup.config.ts                # Build configuration
│
├── README.md                     # Main documentation
├── SKILL.md                      # AI agent usage guide
├── QUICK_START.md                # Quick start guide
├── CHANGELOG.md                  # Version history
├── PROJECT_STRUCTURE.md          # This file
│
├── .gitignore                    # Git ignore rules
└── .npmignore                    # npm publish ignore rules
```

## File Descriptions

### Source Files

#### `src/index.ts`
- Main entry point for the CLI
- Uses `yargs` for command parsing
- Defines all available commands and their options
- Contains help text and usage examples

#### `src/api.ts`
- API client class `PostizAPI`
- Handles all HTTP requests to the Postiz API
- Methods for:
  - Creating posts
  - Listing posts
  - Deleting posts
  - Uploading files
  - Listing integrations
- Error handling and response parsing

#### `src/config.ts`
- Configuration management
- Environment variable handling
- Validates required settings (API key)
- Provides default values

#### `src/commands/posts.ts`
- Post management commands implementation
- `createPost()` - Create new social media posts
- `listPosts()` - List posts with filters
- `deletePost()` - Delete posts by ID

#### `src/commands/integrations.ts`
- Integration management
- `listIntegrations()` - Show connected accounts

#### `src/commands/upload.ts`
- Media upload functionality
- `uploadFile()` - Upload images to Postiz

### Configuration Files

#### `package.json`
- Package name: `postiz`
- Version: `1.0.0`
- Executable bin: `postiz` → `dist/index.js`
- Scripts: `dev`, `build`, `start`, `publish`
- Repository and metadata information

#### `tsconfig.json`
- Extends base config from monorepo
- Target: ES2017
- Module: CommonJS
- Enables decorators and source maps

#### `tsup.config.ts`
- Build tool configuration
- Entry point: `src/index.ts`
- Output format: CommonJS
- Adds shebang for Node.js execution
- Generates source maps

### Documentation Files

#### `README.md`
- Main package documentation
- Installation instructions
- Usage examples
- API reference
- Development guide

#### `SKILL.md`
- Comprehensive guide for AI agents
- Usage patterns and workflows
- Command examples
- Best practices
- Error handling

#### `QUICK_START.md`
- Fast onboarding guide
- Installation steps
- Basic commands
- Common workflows
- Troubleshooting

#### `CHANGELOG.md`
- Version history
- Release notes
- Feature additions
- Bug fixes

### Example Files

#### `examples/basic-usage.sh`
- Bash script example
- Demonstrates basic CLI workflow
- Shows integration listing, post creation, and deletion

## Build Process

### Development Build

```bash
pnpm run dev
```

- Watches for file changes
- Rebuilds automatically
- Useful during development

### Production Build

```bash
pnpm run build
```

1. Cleans `dist/` directory
2. Compiles TypeScript → JavaScript
3. Bundles dependencies
4. Adds shebang for executable
5. Generates source maps
6. Makes output executable

### Output

- `dist/index.js` - Main executable (~490KB)
- `dist/index.js.map` - Source map (~920KB)

## Commands Architecture

### Command Flow

```
User Input
    ↓
index.ts (yargs parser)
    ↓
Command Handler (posts.ts, integrations.ts, upload.ts)
    ↓
config.ts (get API key)
    ↓
api.ts (make API request)
    ↓
Response / Error
    ↓
Output to console
```

### Available Commands

1. **posts:create**
   - Options: `--content`, `--integrations`, `--schedule`, `--image`
   - Handler: `commands/posts.ts::createPost()`

2. **posts:list**
   - Options: `--page`, `--limit`, `--search`
   - Handler: `commands/posts.ts::listPosts()`

3. **posts:delete**
   - Positional: `<id>`
   - Handler: `commands/posts.ts::deletePost()`

4. **integrations:list**
   - No options
   - Handler: `commands/integrations.ts::listIntegrations()`

5. **upload**
   - Positional: `<file>`
   - Handler: `commands/upload.ts::uploadFile()`

## Environment Variables

| Variable | Required | Default | Usage |
|----------|----------|---------|-------|
| `POSTIZ_API_KEY` | ✅ Yes | - | Authentication token |
| `POSTIZ_API_URL` | ❌ No | `https://api.postiz.com` | Custom API endpoint |

## Dependencies

### Runtime Dependencies (from root)
- `yargs` - CLI argument parsing
- `node-fetch` - HTTP requests
- Standard Node.js modules (`fs`, `path`)

### Dev Dependencies
- `tsup` - TypeScript bundler
- `typescript` - Type checking
- `@types/yargs` - TypeScript types

## Integration Points

### With Monorepo

1. **Build Scripts**
   - Added to root `package.json`
   - `pnpm run build:cli` - Build the CLI
   - `pnpm run publish-cli` - Publish to npm

2. **TypeScript Config**
   - Extends `tsconfig.base.json`
   - Shares common compiler options

3. **Dependencies**
   - Uses shared dependencies from root
   - No duplicate packages

### With Postiz API

1. **Endpoints Used**
   - `POST /public/v1/posts` - Create post
   - `GET /public/v1/posts` - List posts
   - `DELETE /public/v1/posts/:id` - Delete post
   - `GET /public/v1/integrations` - List integrations
   - `POST /public/v1/upload` - Upload media

2. **Authentication**
   - API key via `Authorization` header
   - Configured through environment variable

## Publishing

### To npm

```bash
pnpm run publish-cli
```

This will:
1. Build the package
2. Publish to npm with public access
3. Include only `dist/`, `README.md`, and `SKILL.md`

### Package Contents (via .npmignore)

**Included:**
- `dist/` - Compiled code
- `README.md` - Documentation

**Excluded:**
- `src/` - Source code
- `examples/` - Examples
- Config files
- Other markdown files

## Testing

### Manual Testing

```bash
# Test help
node dist/index.js --help

# Test without API key (should error)
node dist/index.js posts:list

# Test with API key (requires valid key)
POSTIZ_API_KEY=test node dist/index.js integrations:list
```

### Automated Testing (Future)

- Unit tests for API client
- Integration tests for commands
- E2E tests with mock API

## Future Enhancements

1. **More Commands**
   - Analytics retrieval
   - Team management
   - Settings configuration

2. **Features**
   - Interactive mode
   - Config file support (~/.postizrc)
   - Output formatting (JSON, table, CSV)
   - Verbose/debug mode
   - Batch operations from file

3. **Developer Experience**
   - TypeScript types export
   - Programmatic API
   - Plugin system
   - Custom integrations

## Support

- **Issues:** https://github.com/gitroomhq/postiz-app/issues
- **Docs:** See README.md, SKILL.md, QUICK_START.md
- **Website:** https://postiz.com