---
name: Scan - Source Code and Extract Data
description: Scan source code and existing documentation, extract API endpoints and business rules
next_step: step-02-generate.md
---

## STEP 01: Scan — Source Code and Existing Documentation

### Purpose

Based on the type detected in step-00, scan the appropriate source and extract data needed for documentation generation.

### Execution By Type

#### For `user` Type (Functional Module)

**MANDATORY FIRST STEP: Read the REAL page TSX before extracting.**
The Mock UI must match the actual interface, NOT a generic KPI/table layout.

**Workflow:**

1. **Read the REAL page TSX**
   - Find: `web/smartstack-web/src/pages/{Application}/{Module}Page.tsx` (e.g., `TenantsTemplatePage.tsx`, `UsersPage.tsx`)
   - Understand the actual layout (cards, table, kanban, etc.)
   - Note the exact components, icons, badges, stats shown

2. **Extract API Endpoints** from the controller
   - Locate: `src/SmartStack.Api/Controllers/{Module}Controller.cs` (singularized)
   - Scan for `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`
   - Parse `[NavRoute]`, `[RequirePermission]` attributes
   - Resolve permission constants from `Permissions.cs`

3. **Extract Business Rules** from Domain entity and tests
   - Locate: `src/SmartStack.Domain/Entities/{Module}/{Entity}.cs`
   - Scan for guard clauses: `if (...) throw new DomainException("...")`
   - Scan validation in Create/Update methods
   - Find unit tests: `src/SmartStack.Domain.Tests/{Module}/{Entity}Tests.cs`
   - Look for `[Fact]` test methods and edge case scenarios
   - Auto-assign BR-XXX IDs and categorize:
     - **Validation:** Required fields, format checks
     - **Security:** Password rules, access control
     - **Business Logic:** State transitions, calculations

#### For `developer` Type (Development Tool)

1. **Locate source reference**
   - `_resources/developer-tools/` or web search for current versions
   - Extract: purpose, installation, setup, common commands, screenshots

2. **Reference available developer tools catalog**
   - Local Environment: Docker Compose, MailDev, VS Code, Environment variables
   - API Testing: Postman, REST Client, Swagger/OpenAPI
   - E2E Testing: Microsoft Playwright, Inspector, Trace Viewer
   - Load Testing: NBomber (.NET), k6, Azure Load Testing
   - Security Testing: OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS

#### For `database` Type (Schema)

1. **Locate schema configuration**
   - Find: `src/SmartStack.Infrastructure/Persistence/Configurations/{Schema}Configuration.cs`
   - Find: `ApplicationDbContextModelSnapshot.cs` for complete schema

2. **Extract:**
   - Table structure (columns, types, constraints)
   - Relationships (foreign keys, one-to-many, many-to-many)
   - Indexes and unique constraints

#### For `testing` Type (Testing Tool)

1. **Locate testing reference**
   - Current test patterns in project
   - External tool documentation (Playwright, NBomber, Snyk, etc.)

2. **Extract:**
   - Tool purpose and integration points
   - Test execution patterns
   - Result interpretation

#### For `update` Type

Re-read the real page TSX and controller to refresh extracted data:

```
1. Read real page TSX → check if interface changed
2. Read controller → check for new/modified API endpoints
3. Read Domain entity → check for new business rules
4. Gather timestamps for doc-manifest.json update
```

### Output

At end of this step, collected data:

| Type | Data Collected |
|------|-----------------|
| `user` | Real page interface, API endpoints array, Business rules array |
| `developer` | Tool metadata, setup steps, commands, examples |
| `database` | Schema structure, relationships, constraints |
| `testing` | Tool integration, test patterns, execution flow |
| `update` | Changed UI elements, new endpoints, new rules, new timestamps |

### Success Metrics

- [x] Real page TSX read and interface documented (user type)
- [x] API endpoints extracted with correct HTTP methods and routes
- [x] Business rules categorized with BR-IDs and statements
- [x] Permission constants resolved from Permissions.cs
- [x] Mock data template identified (5+ realistic records)
- [x] KPI stats template documented (Total, Active, Status breakdown)

### Next Step

→ **step-02-generate.md** — Generate documentation content based on scanned data.
