Chore/setup dev environment

.github/copilot-instructions.md

@@ -12,14 +12,29 @@
 - **Infrastructure**: AWS CDK
 - **Modules**: Separate repositories (`@ciscode/*` packages)
 
-### Backend Module Architecture
+### Architecture Strategy: Application vs Modules
+
+**🏢 ComptAlEyes Application (backend/src/modules/):**
+**→ 4-Layer Clean Architecture** (for complex business logic)
+
+**📦 External Modules (@ciscode/\*):**
+**→ Controller-Service-Repository** (for simplicity and reusability)
+
+> **Why different approaches?**
+> - **Applications** have complex, evolving business logic requiring strict layer separation
+> - **Modules** are reusable libraries that need to be simple, well-tested, and easy to integrate
+> - Clean Architecture in apps, pragmatic CSR in modules = best of both worlds
+
+### Backend Module Architecture (Application)
 **ALWAYS follow 4-layer Clean Architecture for business modules:**
 
 ```
-modules/
+backend/src/modules/
   └── {module-name}/
       ├── api/                    # Controllers, DTOs, HTTP layer
       │   ├── {name}.controller.ts
+      │   ├── guards/             # Module-specific guards
+      │   ├── decorators/         # Module-specific decorators
       │   └── dto/
       ├── application/            # Use-cases, business orchestration
       │   ├── ports/              # Interfaces/contracts
@@ -32,6 +47,9 @@ modules/
 
 **Exception**: Utilities in `core/` (health, logging, config) can be simpler structures.
 
+**See module-specific copilot-instructions.md for details.**
+
+
 ### Core vs Shared
 
 **`core/`** - NestJS-specific, framework-dependent:
@@ -770,6 +788,66 @@ Before declaring a task complete, verify:
 
 ---
 
+## 🔀 Git Workflow & Branching Strategy
+
+### Branch Structure
+
+**Main Branches:**
+- `master` - **Production-ready code** (solo release)
+- `develop` - **Development branch** (integrazione continua)
+
+**Supporting Branches:**
+- `feature/*` - Nuove feature
+- `bugfix/*` - Bug fix
+- `refactor/*` - Refactoring
+- `chore/*` - Manutenzione
+
+### Workflow Completo
+
+**1. Staccare branch da develop:**
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/TASK-123-description
+```
+
+**2. Sviluppo e commit:**
+```bash
+# Lavora sul feature branch
+git add .
+git commit -m "feat(module): description [TASK-123]"
+git push origin feature/TASK-123-description
+```
+
+**3. Pull Request verso develop:**
+```bash
+# PR: feature/TASK-123-description → develop
+# Dopo review e merge, il codice entra in develop
+```
+
+**4. Release (solo quando pronto):**
+```bash
+# Quando develop è stabile e pronto per release:
+git checkout master
+git merge develop
+git tag v1.2.0
+git push origin master --tags
+```
+
+### ⚠️ IMPORTANTE
+
+**SEMPRE:**
+- ✅ Stacca branch da `develop`
+- ✅ PR verso `develop`
+- ✅ Merge su `master` solo per release
+
+**MAI:**
+- ❌ Branch da `master` (tranne hotfix critici)
+- ❌ PR dirette a `master`
+- ❌ Commit diretti su `master` o `develop`
+
+---
+
 ## 🔀 Git Commit Convention
 
 ### Conventional Commits Format

.github/prompts/clone-module.md

@@ -0,0 +1,161 @@
+# 📦 Clone Module for Local Development
+
+**Purpose:** Clone a @ciscode/* module repository for local development alongside ComptAlEyes app.
+
+---
+
+## Instructions for AI Assistant
+
+When a user requests to clone a module for local development, follow these steps:
+
+### 1. Verify Workspace Structure
+
+Check that we're in the ComptAlEyes workspace:
+```bash
+pwd  # Should show: .../comptaleyes
+```
+
+### 2. Check Available Modules
+
+Show modules already available:
+```bash
+npm run module:list
+```
+
+### 3. Ask User for Module Details
+
+Prompt user for:
+- **Module name** (e.g., `auth-kit`, `database-kit`, `auth-kit-ui`)
+- **Repository URL** (if not standard @ciscode/* repo)
+
+### 4. Navigate to Modules Directory
+
+```bash
+cd ..
+# Create modules directory if it doesn't exist
+mkdir -p modules
+cd modules
+```
+
+### 5. Clone the Module
+
+```bash
+# Clone with appropriate directory name
+git clone <repo-url> <module-name>
+
+# Example:
+# git clone https://github.com/ciscode/authentication-kit.git auth-kit
+```
+
+### 6. Verify Module Structure
+
+Check that the cloned module has:
+- ✅ `package.json` with correct package name (e.g., `@ciscode/authentication-kit`)
+- ✅ `src/` directory
+- ✅ `tsconfig.json` or build configuration
+- ✅ Build script (`build` or `build:watch`)
+
+### 7. Install Module Dependencies
+
+```bash
+cd <module-name>
+npm install
+```
+
+### 8. Return to Main App
+
+```bash
+cd ../../comptaleyes
+```
+
+### 9. Verify Auto-Discovery
+
+```bash
+npm run module:list
+```
+
+The newly cloned module should appear in the list.
+
+### 10. Provide Next Steps
+
+Tell user:
+```
+✅ Module '<module-name>' cloned successfully!
+
+Next steps:
+1. Run 'npm run module:setup' for interactive setup
+2. Or manually link: 'npm run module:link <module-name>'
+3. Start watch mode in module: 'cd ../modules/<module-name> && npm run build:watch'
+```
+
+---
+
+## Expected Directory Structure After Clone
+
+```
+your-workspace/
+├── comptaleyes/              (main app - current directory)
+│   ├── scripts/
+│   ├── backend/
+│   └── frontend/
+└── modules/                  (parent level - ../modules)
+    ├── auth-kit/            (newly cloned)
+    ├── database-kit/
+    └── ...
+```
+
+---
+
+## Error Handling
+
+**If modules/ doesn't exist:**
+- Create it at parent level: `mkdir -p ../modules`
+
+**If module already exists:**
+- Ask user if they want to:
+  - Pull latest changes (`git pull`)
+  - Delete and re-clone
+  - Skip
+
+**If package.json missing or invalid:**
+- Warn user that auto-discovery won't work
+- Suggest checking repository URL
+
+**If git clone fails:**
+- Check repository URL
+- Check git credentials
+- Check network connection
+
+---
+
+## Validation Checklist
+
+After cloning, verify:
+- [ ] Module exists in `../modules/<module-name>`
+- [ ] `package.json` exists with valid `@ciscode/*` package name
+- [ ] Dependencies installed (`node_modules/` exists)
+- [ ] Module appears in `npm run module:list`
+- [ ] Can be linked via `npm run module:link <module-name>`
+
+---
+
+## Example Usage
+
+**User says:** "Clone the database-kit module for local development"
+
+**AI should:**
+1. Navigate to `../modules`
+2. Clone: `git clone <database-kit-repo-url> database-kit`
+3. Install deps: `cd database-kit && npm install`
+4. Return to app: `cd ../../comptaleyes`
+5. Verify: `npm run module:list` shows database-kit
+6. Provide next steps message
+
+---
+
+## Notes
+
+- ✅ Scripts are portable (use relative paths)
+- ⚠️ Module MUST be at `../modules/<name>` relative to main app
+- ✅ Module name in directory should match what users use in commands
+- ✅ Package name in `package.json` is what matters for linking