# 📦 Apex Package Structure

## Standard Python Package Layout (src-layout)

This package follows the modern **src-layout** convention, which is the recommended best practice for Python packages.

```
apex-package/
│
├── src/
│   └── apex/                    # Main package code
│       ├── __init__.py          # Package version & exports
│       │
│       ├── core/                # Core functionality
│       │   ├── config/          # Settings (Pydantic BaseSettings)
│       │   ├── security/        # Password hashing, JWT
│       │   ├── authentication/  # Auth dependencies
│       │   ├── permissions/     # RBAC dependencies
│       │   └── utils/           # Utility functions (tokens, etc.)
│       │
│       ├── domain/              # Business logic layer
│       │   ├── models/          # Base models (User, Org, Role, Permission)
│       │   ├── repositories/    # Repository pattern
│       │   └── services/        # Business services (Auth, User, PasswordReset)
│       │
│       ├── infrastructure/      # External adapters
│       │   ├── database/        # SQLAlchemy setup, session management
│       │   ├── email/           # Email adapters & templates
│       │   ├── storage/         # File storage (Local, S3-ready)
│       │   └── paypal/          # PayPal integration (ONLY)
│       │       ├── client.py
│       │       ├── service.py
│       │       ├── webhooks.py
│       │       ├── schemas.py
│       │       └── exceptions.py
│       │
│       ├── api/                 # API layer
│       │   └── v1/              # API version 1
│       │       ├── auth/        # Authentication routes
│       │       ├── users/       # User CRUD
│       │       ├── organizations/ # Organization CRUD
│       │       ├── roles/       # Role CRUD
│       │       ├── permissions/ # Permission CRUD
│       │       ├── modules/     # Feature flags
│       │       ├── settings/    # User/Org settings
│       │       ├── payments/    # PayPal endpoints
│       │       └── schemas/     # Pydantic schemas
│       │
│       ├── migrations/          # Alembic templates
│       │   ├── env.py
│       │   └── script.py.mako
│       │
│       └── cli/                 # CLI utilities
│           ├── __init__.py
│           └── main.py          # Typer CLI commands
│
├── tests/                       # Unit & integration tests
│   ├── __init__.py
│   └── test_main.py             # Basic package tests
│
├── README.md                    # Main documentation (shown on PyPI)
├── IMPLEMENTATION_COMPLETE.md   # Implementation status
├── LICENSE                      # MIT License
├── pyproject.toml               # Build config & metadata (PEP 621)
├── MANIFEST.in                  # Extra files to include in distribution
├── .env.example                 # Environment configuration template
└── .gitignore                   # Git ignore patterns
```

## 📋 File Purposes

### Root Level

| File | Purpose |
|------|---------|
| `src/` | Contains the actual package code (modern best practice) |
| `tests/` | Unit and integration tests (not included in distribution) |
| `README.md` | Main documentation, displayed on PyPI |
| `LICENSE` | MIT License |
| `pyproject.toml` | Package metadata, dependencies, build config (PEP 621 standard) |
| `MANIFEST.in` | Specifies additional files to include in source distribution |
| `.env.example` | Template for environment variables |
| `.gitignore` | Git ignore patterns |

### Package Code (`src/apex/`)

| Module | Purpose |
|--------|---------|
| `__init__.py` | Package version & public API exports |
| `core/` | Core functionality (config, security, auth, permissions) |
| `domain/` | Business logic (models, repositories, services) |
| `infrastructure/` | External integrations (database, email, storage, PayPal) |
| `api/` | FastAPI routers and Pydantic schemas |
| `migrations/` | Alembic migration templates |
| `cli/` | Command-line interface (Typer) |

## 🎯 Why src-layout?

The `src/` layout provides several benefits:

1. **Import Testing** - Ensures you're testing the installed package, not local files
2. **Prevents Accidental Imports** - Can't accidentally import from development directory
3. **Cleaner Namespace** - Root directory doesn't mix code with config files
4. **Modern Standard** - Recommended by Python Packaging Authority (PyPA)
5. **Build Tool Compatibility** - Works better with setuptools, poetry, hatch, etc.

## 📦 Installation

### Development Installation

```bash
# Install in editable mode with dev dependencies
pip install -e '.[dev]'
```

### Production Installation

```bash
pip install apex
```

### Verify Installation

```bash
# Check CLI is available
apex version

# Run tests
pytest tests/
```

## 🔧 Development Workflow

1. **Edit code** in `src/apex/`
2. **Write tests** in `tests/`
3. **Run tests**: `pytest`
4. **Build package**: `python -m build`
5. **Test locally**: `pip install -e .`
6. **Publish**: `twine upload dist/*`

## 📊 Package Statistics

- **68 Python files**
- **8 API routers** (full CRUD)
- **40+ endpoints**
- **Complete PayPal integration**
- **100% type-hinted**
- **Zero Stripe dependencies** ✅

## 🚀 Usage

```python
# Import from the installed package
from apex.domain.models import BaseUser, BaseOrganization
from apex.core.config import get_settings
from apex.api.v1 import auth_router, users_router

# Your code here...
```

## 📚 Related Documentation

- **README.md** - Getting started & usage guide
- **IMPLEMENTATION_COMPLETE.md** - Detailed feature list
- **.env.example** - Configuration reference
- **pyproject.toml** - Package metadata & dependencies

---

**Package Name:** apex  
**Version:** 0.1.0  
**Structure:** ✅ Modern src-layout  
**Ready for:** PyPI publication

