# Architecture Decision: Project Structure

## Current State

Projects generated by paxx use an `features/` directory for feature modules:

```
my_project/
├── features/
│   ├── products/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── models.py
│   │   ├── routes.py
│   │   ├── schemas.py
│   │   └── services.py
│   └── users/
├── core/
├── main.py
└── settings.py
```

Imports look like: `from features.products import services`

## The Question

Is `features/` the right name and structure? It works but carries Django baggage and may not resonate with FastAPI developers.

## Options

### Option 1: Keep `features/` (current)

**Pros:**
- Familiar to Django developers
- Already implemented
- Clear grouping of feature modules

**Cons:**
- Django-ism that may feel dated
- `features.` prefix in every import
- May signal "this is Django-like" when it's not

### Option 2: Rename to `features/`

```
my_project/
├── features/
│   ├── products/
│   └── users/
├── core/
└── main.py
```

**Pros:**
- More descriptive - "these are your domain features"
- Modern, framework-agnostic terminology
- Still provides visual grouping
- Imports: `from features.products import services`

**Cons:**
- Still has a prefix in imports
- Less common in Python ecosystem

### Option 3: Rename to `modules/`

```
my_project/
├── modules/
│   ├── products/
│   └── users/
```

**Pros:**
- Generic, framework-agnostic
- Common term in other ecosystems (Node.js, etc.)

**Cons:**
- "Module" already means something in Python
- Could be confusing

### Option 4: Rename to `api/`

```
my_project/
├── api/
│   ├── products/
│   └── users/
├── core/
└── main.py
```

**Pros:**
- Clear intent - this is an API framework
- Short prefix: `from api.products import ...`
- Intuitive for API developers

**Cons:**
- What if someone wants non-API code in there?
- Mixing concerns (routes + models + services all under "api")

### Option 5: Flat structure (no grouping directory)

```
my_project/
├── products/
│   ├── routes.py
│   ├── models.py
│   └── services.py
├── users/
├── core/
└── main.py
```

**Pros:**
- Simplest imports: `from products import services`
- Matches most FastAPI tutorials
- No artificial grouping

**Cons:**
- Feature modules mixed with infrastructure (`core/`)
- Harder to visually distinguish "my features" from "framework stuff"
- Top-level gets cluttered as project grows

### Option 6: `src/` layout with project name

```
my_project/
├── src/
│   └── my_project/
│       ├── products/
│       ├── users/
│       ├── core/
│       └── main.py
├── tests/
└── pyproject.toml
```

**Pros:**
- Modern Python packaging standard (PEP 517/518)
- Works well for installable packages
- Imports use project name: `from my_project.products import ...`

**Cons:**
- More boilerplate
- Overkill for simple APIs
- Requires `pyproject.toml` configuration

## Recommendation

**`features/`** seems like the best balance:

1. **Descriptive** - clearly communicates "this is where domain features live"
2. **Modern** - no Django baggage
3. **Grouped** - maintains visual separation from infrastructure code
4. **Reasonable imports** - `from features.products import ...` is acceptable

The flat structure (Option 5) is tempting for simplicity but loses the "at a glance" understanding of what's a feature vs infrastructure.

## Migration Impact

Changing from `features/` to another name requires updating:

1. Project templates (`src/paxx/templates/project/`)
2. Feature templates (`src/paxx/templates/features/feature_blueprint/`)
3. Contrib plugins (`src/paxx/contrib/`)
4. CLI commands (`startfeature`, `add`)
5. Documentation

## Decision

TBD - awaiting input.
