# Story 5.22: Remove Obsolete structlog References

## Status: Complete

## Priority: High

## Estimated Effort: Small (0.5 day)

## Dependencies: None

## Epic: Documentation Cleanup

---

## Context

A comprehensive code audit confirmed that fapilog has **zero runtime dependencies on structlog**. The library implements its own structured logging pipeline from scratch. However, several documentation files contain obsolete or inaccurate references to structlog that incorrectly suggest it is a dependency or foundation of fapilog.

These inaccuracies cause confusion for:

- New users trying to understand fapilog's architecture
- Contributors who may incorrectly assume structlog knowledge is required
- Security auditors reviewing dependency chains

---

## Problem Statement

1. **False dependency claims**: Documentation incorrectly states structlog is a foundation/dependency
2. **Obsolete code examples**: Contributing guides show `import structlog` with non-existent functions
3. **Misleading tech stack**: Architecture docs list structlog as "internal structured logging"
4. **Unnecessary build dependency**: `docs/requirements.txt` includes structlog for autodoc

---

## Scope of Changes

### Files Requiring Updates

| File                              | Issue                                                       | Severity |
| --------------------------------- | ----------------------------------------------------------- | -------- |
| `docs/requirements.txt`           | Lists `structlog` as doc build dependency                   | Medium   |
| `docs/appendices.md`              | Claims structlog is "Structured logging foundation"         | Critical |
| `docs/architecture.md`            | States structlog used for "Internal structured logging"     | Critical |
| `docs/architecture/tech-stack.md` | Same incorrect structlog claim                              | Critical |
| `CONTRIBUTING.md`                 | Shows `import structlog` example with non-existent function | High     |
| `docs/contributing.md`            | Same obsolete example                                       | High     |

---

## Acceptance Criteria

### AC1: Remove structlog from docs/requirements.txt

- [ ] Remove `structlog` line from `docs/requirements.txt`
- [ ] Verify documentation builds successfully without structlog
- [ ] Confirm no autodoc features depend on structlog

### AC2: Fix docs/appendices.md

- [ ] Remove structlog from dependencies section
- [ ] Update any dependency descriptions that reference structlog

### AC3: Fix docs/architecture.md

- [ ] Remove structlog from tech stack table
- [ ] Update "Internal structured logging" description to reflect fapilog's own implementation
- [ ] Clarify that fapilog implements its own structured logging pipeline

### AC4: Fix docs/architecture/tech-stack.md

- [ ] Remove structlog from dependencies list
- [ ] Update description to accurately describe fapilog's architecture

### AC5: Fix CONTRIBUTING.md

- [ ] Remove `import structlog` example
- [ ] Remove reference to non-existent `configure_logging` function
- [ ] Replace with accurate fapilog import and usage example

### AC6: Fix docs/contributing.md

- [ ] Apply same fixes as CONTRIBUTING.md
- [ ] Ensure consistency between the two files

### AC7: Verify No Other References

- [ ] Run `grep -r "structlog" .` to find any other references
- [ ] Review and fix any additional occurrences (excluding legitimate comparison docs)

---

## Technical Details

### Current Incorrect Content

**docs/appendices.md** (line ~25):

```markdown
| structlog | Structured logging foundation |
```

**docs/architecture.md** (tech stack section):

```markdown
| structlog | Internal structured logging |
```

**docs/architecture/tech-stack.md** (similar):

```markdown
| structlog | Internal structured logging |
```

**CONTRIBUTING.md** and **docs/contributing.md** (example code):

```python
import structlog
from fapilog import configure_logging  # This function doesn't exist

configure_logging()
logger = structlog.get_logger()
```

**docs/requirements.txt**:

```
structlog
```

### Correct Replacements

**docs/appendices.md** - Remove the structlog row entirely or replace with:

```markdown
| fapilog.core | Native structured logging implementation |
```

**docs/architecture.md** and **docs/architecture/tech-stack.md** - Remove structlog row or clarify:

```markdown
| fapilog | Native async structured logging (no external logging framework) |
```

**CONTRIBUTING.md** and **docs/contributing.md** - Replace example with:

```python
from fapilog import get_logger

logger = get_logger()
logger.info("Development server started", port=8000)
```

**docs/requirements.txt** - Simply remove the `structlog` line.

---

## Legitimate structlog References (Do NOT Remove)

The following files correctly mention structlog as a **comparison/alternative** and should NOT be modified:

- `docs/user-guide/comparisons.md` - Compares fapilog vs structlog (legitimate)
- `docs/faq.md` - FAQ about structlog vs fapilog (legitimate)
- `docs/documentation-structure.md` - Mentions migration from structlog (legitimate)

---

## Test Plan

### Manual Verification

1. **Documentation Build**:

   ```bash
   cd docs
   pip install -r requirements.txt  # Should succeed without structlog
   make html  # Should build without errors
   ```

2. **Link Verification**:

   ```bash
   python docs/validate_links.py
   ```

3. **Grep Verification**:

   ```bash
   # Should only return comparison/faq files
   grep -rn "structlog" docs/ --include="*.md" | grep -v comparisons | grep -v faq | grep -v documentation-structure
   ```

4. **Code Verification**:
   ```bash
   # Should return zero results
   grep -rn "structlog" src/
   grep -rn "structlog" tests/
   ```

---

## Implementation Steps

1. **Update docs/requirements.txt**:

   - Remove the `structlog` line
   - Test doc build

2. **Update docs/appendices.md**:

   - Find and remove/replace the structlog dependency row
   - Verify table formatting

3. **Update docs/architecture.md**:

   - Remove structlog from tech stack
   - Update description to clarify fapilog's native implementation

4. **Update docs/architecture/tech-stack.md**:

   - Same changes as architecture.md

5. **Update CONTRIBUTING.md**:

   - Find the code example section
   - Replace structlog import with fapilog import
   - Remove non-existent `configure_logging` function
   - Update example to use `get_logger()`

6. **Update docs/contributing.md**:

   - Mirror changes from CONTRIBUTING.md

7. **Final grep sweep**:
   - Search for any remaining structlog references
   - Verify only legitimate comparison references remain

---

## Backwards Compatibility

- Documentation-only changes
- No code changes required
- No API changes
- No breaking changes

---

## Definition of Done

- [ ] All six files updated as specified
- [ ] Documentation builds without structlog dependency
- [ ] No inaccurate structlog references remain
- [ ] Legitimate comparison references preserved
- [ ] Changes reviewed and merged

---

## Related Stories

- Story 5.16: Filter Plugin Type Metadata Validation (also documentation accuracy)
- Future: Comprehensive documentation audit
