vibes-plug 1.0.0 → 2.5.0

package/skills/saas-transformer/scripts/saas_transformation_scanner.py

@@ -12,9 +12,15 @@ import re
 from pathlib import Path
 from typing import Dict, List
 
+# Ensure UTF-8 output on Windows consoles
+if hasattr(sys.stdout, 'reconfigure'):
+    sys.stdout.reconfigure(encoding='utf-8')
+if hasattr(sys.stderr, 'reconfigure'):
+    sys.stderr.reconfigure(encoding='utf-8')
+
 
 class SaasTransformationScanner:
-    """Scans an existing codebase for SaaS transformation readiness across 8 pillars."""
+    """Scans an existing codebase for SaaS transformation readiness across 7 key pillars."""
 
     PILLAR_WEIGHTS = {
         'tenancy': 0.20,
@@ -108,14 +114,14 @@ class SaasTransformationScanner:
 
     def _grep_project(self, pattern: str, extensions: List[str] = None) -> List[str]:
         matches = []
-        exts = extensions or ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.prisma']
+        exts = extensions or ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.prisma', '.sql', '.yaml', '.yml', '.json']
         for ext in exts:
             for f in self.target_path.rglob(f'*{ext}'):
-                if any(x in str(f) for x in ['node_modules', '.next', 'dist', '.git']):
+                if any(x in str(f) for x in ['node_modules', '.next', 'dist', '.git', 'target', '.venv']):
                     continue
                 try:
-                    content = f.read_text(errors='ignore')
-                    if re.search(pattern, content):
+                    content = f.read_text(encoding='utf-8', errors='ignore')
+                    if re.search(pattern, content, re.IGNORECASE):
                         matches.append(str(f.relative_to(self.target_path)))
                 except (IOError, OSError):
                     continue
@@ -125,91 +131,95 @@ class SaasTransformationScanner:
         p = self._init_pillar('tenancy', 'Multi-Tenancy Foundation')
         
         # Check database schema structure
-        has_db_schema = self._file_exists('prisma/schema.prisma') or self._grep_project('pgTable|sqliteTable|mysqlTable', ['.ts', '.js'])
-        self._check(p, 'Database schema config exists', has_db_schema, severity='critical')
+        has_db_schema = self._file_exists('prisma/schema.prisma', 'drizzle.config.ts', 'drizzle.config.js') or self._grep_project(r'pgTable|sqliteTable|mysqlTable|schema\.createTable|Base\.metadata', ['.ts', '.js', '.py'])
+        self._check(p, 'Database schema config exists', bool(has_db_schema), severity='critical')
 
         # Check tenant id usage
-        tenant_cols = self._grep_project(r'tenant_id|tenantId|workspace_id|workspaceId', ['.prisma', '.ts', '.js'])
+        tenant_cols = self._grep_project(r'tenant_id|tenantId|workspace_id|workspaceId|org_id|orgId', ['.prisma', '.ts', '.js', '.py', '.go', '.sql'])
         self._check(p, 'tenant_id/workspace_id column configured in models', len(tenant_cols) > 0, severity='critical')
 
         # Check RLS
-        has_rls = self._grep_project(r'ROW LEVEL SECURITY|ENABLE RLS|enableRowLevelSecurity', ['.sql', '.ts', '.js'])
-        self._check(p, 'PostgreSQL RLS setup or database policies present', len(has_rls) > 0)
+        has_rls = self._grep_project(r'ROW LEVEL SECURITY|ENABLE RLS|enableRowLevelSecurity|createPolicy', ['.sql', '.ts', '.js', '.py'])
+        self._check(p, 'PostgreSQL RLS setup or database isolation policies present', len(has_rls) > 0)
 
         # Check Tenant Middleware
-        has_mw = self._grep_project(r'tenantMiddleware|app\.current_tenant_id|tenantContext', ['.ts', '.js', '.py', '.go'])
+        has_mw = self._grep_project(r'tenantMiddleware|app\.current_tenant_id|tenantContext|workspaceMiddleware', ['.ts', '.js', '.py', '.go'])
         self._check(p, 'Tenant-aware middleware initialized', len(has_mw) > 0)
 
     def _audit_auth(self):
         p = self._init_pillar('auth', 'Authentication & Authorization')
 
         # Auth service provider detection
-        has_clerk = self._grep_project(r'clerkMiddleware|@clerk/nextjs', ['.ts', '.tsx', '.json'])
-        has_nextauth = self._grep_project(r'NextAuth|auth\.js', ['.ts', '.js'])
-        has_supabase_auth = self._grep_project(r'supabase\.auth|@supabase/ssr', ['.ts', '.tsx', '.js'])
-        self._check(p, 'Production auth provider configured (Clerk/NextAuth/Supabase Auth)', 
-                    bool(has_clerk or has_nextauth or has_supabase_auth), severity='critical')
+        has_clerk = self._grep_project(r'clerkMiddleware|@clerk/nextjs|@clerk/clerk-sdk-node', ['.ts', '.tsx', '.json'])
+        has_nextauth = self._grep_project(r'NextAuth|auth\.js|@auth/core|next-auth', ['.ts', '.js', '.json'])
+        has_supabase_auth = self._grep_project(r'supabase\.auth|@supabase/ssr|@supabase/auth-helpers', ['.ts', '.tsx', '.js'])
+        has_firebase_auth = self._grep_project(r'firebase/auth|firebase-admin/auth', ['.ts', '.tsx', '.js', '.json'])
+        has_custom_jwt = self._grep_project(r'jsonwebtoken|jose|PyJWT', ['.ts', '.js', '.py', '.json'])
+
+        has_auth_provider = bool(has_clerk or has_nextauth or has_supabase_auth or has_firebase_auth or has_custom_jwt)
+        self._check(p, 'Production auth provider configured (Clerk/NextAuth/Supabase/Firebase/JWT)', 
+                    has_auth_provider, severity='critical')
 
         # Roles / RBAC
-        has_roles = self._grep_project(r'role\s*:\s*["\'](admin|owner|member)["\']|requireRole|checkPermission', ['.ts', '.tsx', '.js', '.py'])
+        has_roles = self._grep_project(r'role\s*:\s*["\'](admin|owner|member|viewer)["\']|requireRole|checkPermission|hasPermission|RBAC', ['.ts', '.tsx', '.js', '.py', '.go'])
         self._check(p, 'Role-Based Access Control (RBAC) definitions exist', len(has_roles) > 0)
 
     def _audit_billing(self):
         p = self._init_pillar('billing', 'Billing & Subscription')
 
         # Payment Provider dependencies
-        has_stripe = self._grep_project(r'stripe|lemonsqueezy|paddle-sdk', ['.json', '.ts', '.js', '.py'])
-        self._check(p, 'Payment processor integrated (Stripe/LemonSqueezy)', len(has_stripe) > 0, severity='critical')
+        has_stripe = self._grep_project(r'stripe|lemonsqueezy|paddle-sdk|doku-payment|midtrans', ['.json', '.ts', '.js', '.py', '.go'])
+        self._check(p, 'Payment processor integrated (Stripe/LemonSqueezy/DOKU/Midtrans)', len(has_stripe) > 0, severity='critical')
 
         # Webhooks
-        has_webhook = self._grep_project(r'stripe\.webhooks|constructEvent|webhooks/stripe', ['.ts', '.js', '.py'])
+        has_webhook = self._grep_project(r'stripe\.webhooks|constructEvent|webhooks/stripe|doku.*webhook|verifySignature', ['.ts', '.js', '.py', '.go'])
         self._check(p, 'Webhook listener for payment events implemented', len(has_webhook) > 0)
 
         # Pricing and Plans config
-        has_pricing = self._grep_project(r'pricing|plans|subscriptionStatus|tier', ['.ts', '.tsx', '.js'])
+        has_pricing = self._grep_project(r'pricing|plans|subscriptionStatus|tier|PLAN_LIMITS', ['.ts', '.tsx', '.js', '.py'])
         self._check(p, 'Pricing plan definitions present', len(has_pricing) > 0)
 
     def _audit_teams(self):
         p = self._init_pillar('teams', 'Workspace & Team Management')
 
         # Member list / Workspace switcher check
-        has_switcher = self._grep_project(r'workspaceSwitcher|WorkspaceSelect|switchWorkspace', ['.tsx', '.ts', '.js'])
+        has_switcher = self._grep_project(r'workspaceSwitcher|WorkspaceSelect|switchWorkspace|orgSwitcher', ['.tsx', '.ts', '.js'])
         self._check(p, 'Workspace switching controls found', len(has_switcher) > 0)
 
         # Invite flow
-        has_invites = self._grep_project(r'workspace_invitations|inviteMember|invitationToken', ['.prisma', '.ts', '.js'])
+        has_invites = self._grep_project(r'workspace_invitations|inviteMember|invitationToken|team_members', ['.prisma', '.ts', '.js', '.py', '.sql'])
         self._check(p, 'Team invitation system models or methods exist', len(has_invites) > 0)
 
     def _audit_frontend(self):
         p = self._init_pillar('frontend', 'SaaS App Shell & Dashboard')
 
         # Shell and settings pages
-        has_billing_ui = self._grep_project(r'/settings/billing|BillingSettings', ['.tsx', '.ts', '.js'])
+        has_billing_ui = self._grep_project(r'/settings/billing|BillingSettings|SubscriptionSettings', ['.tsx', '.ts', '.js'])
         self._check(p, 'Billing/subscription settings page implemented', len(has_billing_ui) > 0)
 
-        has_team_ui = self._grep_project(r'/settings/team|TeamSettings', ['.tsx', '.ts', '.js'])
+        has_team_ui = self._grep_project(r'/settings/team|TeamSettings|MembersSettings', ['.tsx', '.ts', '.js'])
         self._check(p, 'Team/member settings page implemented', len(has_team_ui) > 0)
 
     def _audit_api(self):
         p = self._init_pillar('api', 'API Layer & Feature Gating')
 
         # Gated flags or plan limits
-        has_gating = self._grep_project(r'PLAN_LIMITS|PLAN_CONFIGS|hasFeature|assertHasFeature', ['.ts', '.tsx', '.js'])
+        has_gating = self._grep_project(r'PLAN_LIMITS|PLAN_CONFIGS|hasFeature|assertHasFeature|useFeatureFlag|checkFeatureGating', ['.ts', '.tsx', '.js', '.py'])
         self._check(p, 'Feature gating / usage limit configuration map defined', len(has_gating) > 0)
 
         # Usage metering log
-        has_metering = self._grep_project(r'usage_records|usageRecords|usageMeter|incrementUsage', ['.prisma', '.ts', '.js'])
+        has_metering = self._grep_project(r'usage_records|usageRecords|usageMeter|incrementUsage|trackUsage', ['.prisma', '.ts', '.js', '.py', '.sql'])
         self._check(p, 'Usage metering / metric tracking database model exists', len(has_metering) > 0)
 
     def _audit_hardening(self):
         p = self._init_pillar('hardening', 'Production Hardening')
 
         # Basic rate limits
-        has_rate_limit = self._grep_project(r'rate.?limit|upstash/ratelimit|limiter', ['.ts', '.js', '.py'])
+        has_rate_limit = self._grep_project(r'rate.?limit|upstash/ratelimit|limiter|slowDown|governor', ['.ts', '.js', '.py', '.go'])
         self._check(p, 'API Rate Limiting setup configured', len(has_rate_limit) > 0)
 
         # Env validation
-        has_env_spec = self._file_exists('.env.example', '.env.template')
+        has_env_spec = self._file_exists('.env.example', '.env.template', '.env.schema')
         self._check(p, 'Environment example schema exists', has_env_spec)
 
     def _calculate_overall_score(self):

package/skills/scalability-clean-code/SKILL.md

@@ -1,229 +1,229 @@
----
-name: scalability-clean-code
-description: "Software architecture guidelines to maintain code readability (Clean Code, SOLID, DRY) and application scalability / Panduan arsitektur perangkat lunak untuk menjaga keterbacaan kode (Clean Code, SOLID, DRY) dan kemampuan skalabilitas aplikasi."
-author: "Roedy Rustam"
----
-
-# Scalability & Clean Code (2026 Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Software architecture guidelines for writing clean, scalable, and maintainable code. Covers SOLID principles, DRY/YAGNI/KISS, Clean Architecture layers, **Vertical Slice Architecture** (the modern alternative to layered architecture), Domain-Driven Design (DDD) patterns, and practical refactoring techniques.
-
-### Trigger Conditions
-- Refactoring a codebase that has become hard to understand or modify.
-- Designing the architecture for a new feature or service.
-- Identifying and eliminating code smells (God Classes, Feature Envy, Long Methods).
-- Deciding between Layered Architecture vs Vertical Slice Architecture.
-- Applying SOLID principles to a specific code problem.
-
-### The SOLID Principles (With Modern Context)
-
-#### Single Responsibility Principle (SRP)
-A module/class/function should have one reason to change. In 2026 React/Node.js context:
-- **Bad**: A React component that fetches data, transforms it, and renders UI.
-- **Good**: Separate `useUserQuery()` hook (fetch), `transformUser()` util (transform), `UserCard` component (render).
-
-#### Open/Closed Principle (OCP)
-Open for extension, closed for modification. Use composition and strategy pattern:
-```typescript
-// Bad: modify existing code every time a new payment provider is added
-function processPayment(type: 'stripe' | 'polar' | 'paypal', amount: number) {
-  if (type === 'stripe') { /* ... */ }
-  else if (type === 'polar') { /* ... */ }
-}
-
-// Good: extend by adding new providers, not modifying existing code
-interface PaymentProvider {
-  charge(amount: number): Promise<Receipt>;
-}
-
-class StripeProvider implements PaymentProvider { ... }
-class PolarProvider implements PaymentProvider { ... }
-
-function processPayment(provider: PaymentProvider, amount: number) {
-  return provider.charge(amount);
-}
-```
-
-#### Dependency Inversion Principle (DIP)
-High-level modules should not depend on low-level modules — both should depend on abstractions:
-```typescript
-// Bad: handler directly imports concrete DB client
-import { db } from './postgres-client';
-
-// Good: inject the repository interface
-interface UserRepository {
-  findById(id: string): Promise<User | null>;
-  save(user: User): Promise<void>;
-}
-
-async function getUser(repo: UserRepository, id: string) {
-  return repo.findById(id);
-}
-```
-
-### Vertical Slice Architecture (VSA)
-The modern alternative to traditional layered architecture (Controller → Service → Repository). Organize code by **feature** (vertical slice) rather than by **technical layer** (horizontal slice):
-
-```
-Traditional (Layered):
-src/
-  controllers/    ← all controllers together
-  services/       ← all services together
-  repositories/   ← all repositories together
-
-Vertical Slice:
-src/
-  features/
-    users/
-      create-user.handler.ts    ← all logic for "create user" in one place
-      create-user.schema.ts
-      create-user.test.ts
-    products/
-      list-products.handler.ts
-      list-products.schema.ts
-```
-
-**Benefits of VSA**:
-- Features are self-contained — easy to add, modify, delete, or move.
-- No need to navigate 3-4 layers just to trace one user story.
-- Natural boundary for microservice extraction.
-
-```typescript
-// features/users/create-user.handler.ts
-// One file contains the complete "create user" vertical slice
-import { z } from 'zod';
-import { db } from '@/lib/db';
-import { sendWelcomeEmail } from '@/lib/email';
-
-export const CreateUserSchema = z.object({
-  name: z.string().min(2),
-  email: z.string().email(),
-});
-
-export type CreateUserInput = z.infer<typeof CreateUserSchema>;
-
-export async function handleCreateUser(input: CreateUserInput) {
-  const validated = CreateUserSchema.parse(input);
-  
-  const user = await db.user.create({ data: validated });
-  await sendWelcomeEmail(user.email, user.name);
-  
-  return user;
-}
-```
-
-### Clean Code Principles
-
-#### Functions
-- **Do one thing**: Functions should do one thing and do it well.
-- **Small**: Aim for < 20 lines. If longer, extract sub-functions.
-- **Descriptive names**: `getUsersByWorkspace()` not `getData()`.
-- **No side effects**: Pure functions are predictable and testable.
-
-#### Naming
-- Variables: noun phrases (`userCount`, `activeWorkspaces`).
-- Functions: verb phrases (`fetchUser`, `validateInput`, `sendEmail`).
-- Boolean: question form (`isActive`, `hasPermission`, `canEdit`).
-- Avoid abbreviations: `workspace` not `ws`, `configuration` not `cfg`.
-
-#### Comments
-- **Don't comment bad code — rewrite it.**
-- Write self-documenting code: well-named variables and functions eliminate the need for most comments.
-- **Do** comment: why (intent), not what (obvious from code).
-
-#### DRY, YAGNI, KISS
-- **DRY**: Don't Repeat Yourself — extract shared logic. But: avoid premature abstraction.
-- **YAGNI**: You Aren't Gonna Need It — don't build features "just in case".
-- **KISS**: Keep It Simple, Stupid — the simplest solution that works is usually best.
-
-### Code Smells & Refactoring
-
-| Smell | Symptom | Refactoring |
-|---|---|---|
-| **God Class** | Class does everything | Extract Class, Move Method |
-| **Long Method** | Method > 30 lines | Extract Method |
-| **Feature Envy** | Method uses another class's data excessively | Move Method |
-| **Data Clumps** | Same 3+ params appear together repeatedly | Introduce Parameter Object |
-| **Magic Numbers** | `if (status === 3)` | Extract Constant |
-| **Shotgun Surgery** | One change requires edits in many places | Move Method, Inline Class |
-| **Primitive Obsession** | Using string/int for domain concepts | Replace with Value Object |
-
-### Architecture Decision Framework
-When choosing an architecture, ask:
-1. **What changes together?** Organize code that changes together.
-2. **What is independently deployable?** Separate services by deployment boundary.
-3. **What has different scaling needs?** Scale independently only what needs it.
-4. **What is the team size?** Microservices add overhead — start monolith, extract when needed.
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan arsitektur perangkat lunak untuk menulis kode yang bersih, skalabel, dan mudah dirawat. Mencakup prinsip SOLID, DRY/YAGNI/KISS, lapisan Clean Architecture, **Vertical Slice Architecture** (alternatif modern dari layered architecture), pola Domain-Driven Design (DDD), dan teknik refactoring praktis.
-
-### Kondisi Pemicu
-- Merefaktor codebase yang sulit dipahami atau dimodifikasi.
-- Merancang arsitektur untuk fitur atau layanan baru.
-- Mengidentifikasi dan menghilangkan code smell (God Class, Feature Envy, Long Method).
-- Memutuskan antara Layered Architecture vs Vertical Slice Architecture.
-- Menerapkan prinsip SOLID pada masalah kode tertentu.
-
-### Prinsip SOLID
-
-#### SRP — Single Responsibility Principle
-Setiap modul/kelas/fungsi harus memiliki satu alasan untuk berubah. Pisahkan pengambilan data, transformasi data, dan rendering UI.
-
-#### OCP — Open/Closed Principle
-Terbuka untuk ekstensi, tertutup untuk modifikasi. Gunakan komposisi dan pola strategi — tambah provider baru tanpa mengubah kode yang ada.
-
-#### DIP — Dependency Inversion Principle
-Modul tingkat tinggi tidak boleh bergantung pada modul tingkat rendah — keduanya harus bergantung pada abstraksi (interface).
-
-### Vertical Slice Architecture (VSA)
-Alternatif modern dari layered architecture tradisional. Organisasikan kode berdasarkan **fitur** (irisan vertikal), bukan lapisan teknis (irisan horizontal).
-
-**Keuntungan VSA:**
-- Fitur bersifat self-contained — mudah ditambah, dimodifikasi, dihapus, atau dipindah.
-- Tidak perlu menavigasi 3-4 layer hanya untuk melacak satu user story.
-- Batas natural untuk ekstraksi microservice.
-
-### Prinsip Clean Code
-
-#### Fungsi
-- Lakukan satu hal dan lakukan dengan baik.
-- Nama deskriptif: `getUsersByWorkspace()` bukan `getData()`.
-- Tanpa efek samping: fungsi murni dapat diprediksi dan diuji.
-
-#### Penamaan
-- Variabel: frasa kata benda (`jumlahPengguna`, `workspaceAktif`).
-- Fungsi: frasa kata kerja (`ambilPengguna`, `validasiInput`).
-- Boolean: bentuk pertanyaan (`aktif`, `punyaIzin`, `bisaEdit`).
-
-#### Komentar
-- Jangan komen kode buruk — tulis ulang.
-- Tulis kode yang mendokumentasikan dirinya sendiri.
-- Komentar: **mengapa** (niat), bukan apa (jelas dari kode).
-
-#### DRY, YAGNI, KISS
-- **DRY**: Jangan ulangi diri sendiri — ekstrak logika bersama.
-- **YAGNI**: Anda tidak akan membutuhkannya — jangan bangun fitur "untuk jaga-jaga".
-- **KISS**: Tetap sederhana — solusi paling sederhana yang berfungsi biasanya terbaik.
-
-### Code Smell & Refactoring
-Identifikasi dan perbaiki: God Class, Long Method, Feature Envy, Data Clumps, Magic Numbers, Shotgun Surgery, Primitive Obsession.
-
-### Framework Keputusan Arsitektur
-1. **Apa yang berubah bersama?** Organisasikan kode yang berubah bersama.
-2. **Apa yang dapat di-deploy secara independen?** Pisahkan layanan berdasarkan batas deployment.
-3. **Apa yang memiliki kebutuhan scaling berbeda?** Scale secara independen hanya yang membutuhkannya.
-4. **Berapa besar tim?** Microservices menambah overhead — mulai monolith, ekstrak saat diperlukan.
+---
+name: scalability-clean-code
+description: "Software architecture guidelines to maintain code readability (Clean Code, SOLID, DRY) and application scalability / Panduan arsitektur perangkat lunak untuk menjaga keterbacaan kode (Clean Code, SOLID, DRY) dan kemampuan skalabilitas aplikasi."
+author: "Roedy Rustam"
+---
+
+# Scalability & Clean Code (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Software architecture guidelines for writing clean, scalable, and maintainable code. Covers SOLID principles, DRY/YAGNI/KISS, Clean Architecture layers, **Vertical Slice Architecture** (the modern alternative to layered architecture), Domain-Driven Design (DDD) patterns, and practical refactoring techniques.
+
+### Trigger Conditions
+- Refactoring a codebase that has become hard to understand or modify.
+- Designing the architecture for a new feature or service.
+- Identifying and eliminating code smells (God Classes, Feature Envy, Long Methods).
+- Deciding between Layered Architecture vs Vertical Slice Architecture.
+- Applying SOLID principles to a specific code problem.
+
+### The SOLID Principles (With Modern Context)
+
+#### Single Responsibility Principle (SRP)
+A module/class/function should have one reason to change. In 2026 React/Node.js context:
+- **Bad**: A React component that fetches data, transforms it, and renders UI.
+- **Good**: Separate `useUserQuery()` hook (fetch), `transformUser()` util (transform), `UserCard` component (render).
+
+#### Open/Closed Principle (OCP)
+Open for extension, closed for modification. Use composition and strategy pattern:
+```typescript
+// Bad: modify existing code every time a new payment provider is added
+function processPayment(type: 'stripe' | 'polar' | 'paypal', amount: number) {
+  if (type === 'stripe') { /* ... */ }
+  else if (type === 'polar') { /* ... */ }
+}
+
+// Good: extend by adding new providers, not modifying existing code
+interface PaymentProvider {
+  charge(amount: number): Promise<Receipt>;
+}
+
+class StripeProvider implements PaymentProvider { ... }
+class PolarProvider implements PaymentProvider { ... }
+
+function processPayment(provider: PaymentProvider, amount: number) {
+  return provider.charge(amount);
+}
+```
+
+#### Dependency Inversion Principle (DIP)
+High-level modules should not depend on low-level modules — both should depend on abstractions:
+```typescript
+// Bad: handler directly imports concrete DB client
+import { db } from './postgres-client';
+
+// Good: inject the repository interface
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+
+async function getUser(repo: UserRepository, id: string) {
+  return repo.findById(id);
+}
+```
+
+### Vertical Slice Architecture (VSA)
+The modern alternative to traditional layered architecture (Controller → Service → Repository). Organize code by **feature** (vertical slice) rather than by **technical layer** (horizontal slice):
+
+```
+Traditional (Layered):
+src/
+  controllers/    ← all controllers together
+  services/       ← all services together
+  repositories/   ← all repositories together
+
+Vertical Slice:
+src/
+  features/
+    users/
+      create-user.handler.ts    ← all logic for "create user" in one place
+      create-user.schema.ts
+      create-user.test.ts
+    products/
+      list-products.handler.ts
+      list-products.schema.ts
+```
+
+**Benefits of VSA**:
+- Features are self-contained — easy to add, modify, delete, or move.
+- No need to navigate 3-4 layers just to trace one user story.
+- Natural boundary for microservice extraction.
+
+```typescript
+// features/users/create-user.handler.ts
+// One file contains the complete "create user" vertical slice
+import { z } from 'zod';
+import { db } from '@/lib/db';
+import { sendWelcomeEmail } from '@/lib/email';
+
+export const CreateUserSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+});
+
+export type CreateUserInput = z.infer<typeof CreateUserSchema>;
+
+export async function handleCreateUser(input: CreateUserInput) {
+  const validated = CreateUserSchema.parse(input);
+  
+  const user = await db.user.create({ data: validated });
+  await sendWelcomeEmail(user.email, user.name);
+  
+  return user;
+}
+```
+
+### Clean Code Principles
+
+#### Functions
+- **Do one thing**: Functions should do one thing and do it well.
+- **Small**: Aim for < 20 lines. If longer, extract sub-functions.
+- **Descriptive names**: `getUsersByWorkspace()` not `getData()`.
+- **No side effects**: Pure functions are predictable and testable.
+
+#### Naming
+- Variables: noun phrases (`userCount`, `activeWorkspaces`).
+- Functions: verb phrases (`fetchUser`, `validateInput`, `sendEmail`).
+- Boolean: question form (`isActive`, `hasPermission`, `canEdit`).
+- Avoid abbreviations: `workspace` not `ws`, `configuration` not `cfg`.
+
+#### Comments
+- **Don't comment bad code — rewrite it.**
+- Write self-documenting code: well-named variables and functions eliminate the need for most comments.
+- **Do** comment: why (intent), not what (obvious from code).
+
+#### DRY, YAGNI, KISS
+- **DRY**: Don't Repeat Yourself — extract shared logic. But: avoid premature abstraction.
+- **YAGNI**: You Aren't Gonna Need It — don't build features "just in case".
+- **KISS**: Keep It Simple, Stupid — the simplest solution that works is usually best.
+
+### Code Smells & Refactoring
+
+| Smell | Symptom | Refactoring |
+|---|---|---|
+| **God Class** | Class does everything | Extract Class, Move Method |
+| **Long Method** | Method > 30 lines | Extract Method |
+| **Feature Envy** | Method uses another class's data excessively | Move Method |
+| **Data Clumps** | Same 3+ params appear together repeatedly | Introduce Parameter Object |
+| **Magic Numbers** | `if (status === 3)` | Extract Constant |
+| **Shotgun Surgery** | One change requires edits in many places | Move Method, Inline Class |
+| **Primitive Obsession** | Using string/int for domain concepts | Replace with Value Object |
+
+### Architecture Decision Framework
+When choosing an architecture, ask:
+1. **What changes together?** Organize code that changes together.
+2. **What is independently deployable?** Separate services by deployment boundary.
+3. **What has different scaling needs?** Scale independently only what needs it.
+4. **What is the team size?** Microservices add overhead — start monolith, extract when needed.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan arsitektur perangkat lunak untuk menulis kode yang bersih, skalabel, dan mudah dirawat. Mencakup prinsip SOLID, DRY/YAGNI/KISS, lapisan Clean Architecture, **Vertical Slice Architecture** (alternatif modern dari layered architecture), pola Domain-Driven Design (DDD), dan teknik refactoring praktis.
+
+### Kondisi Pemicu
+- Merefaktor codebase yang sulit dipahami atau dimodifikasi.
+- Merancang arsitektur untuk fitur atau layanan baru.
+- Mengidentifikasi dan menghilangkan code smell (God Class, Feature Envy, Long Method).
+- Memutuskan antara Layered Architecture vs Vertical Slice Architecture.
+- Menerapkan prinsip SOLID pada masalah kode tertentu.
+
+### Prinsip SOLID
+
+#### SRP — Single Responsibility Principle
+Setiap modul/kelas/fungsi harus memiliki satu alasan untuk berubah. Pisahkan pengambilan data, transformasi data, dan rendering UI.
+
+#### OCP — Open/Closed Principle
+Terbuka untuk ekstensi, tertutup untuk modifikasi. Gunakan komposisi dan pola strategi — tambah provider baru tanpa mengubah kode yang ada.
+
+#### DIP — Dependency Inversion Principle
+Modul tingkat tinggi tidak boleh bergantung pada modul tingkat rendah — keduanya harus bergantung pada abstraksi (interface).
+
+### Vertical Slice Architecture (VSA)
+Alternatif modern dari layered architecture tradisional. Organisasikan kode berdasarkan **fitur** (irisan vertikal), bukan lapisan teknis (irisan horizontal).
+
+**Keuntungan VSA:**
+- Fitur bersifat self-contained — mudah ditambah, dimodifikasi, dihapus, atau dipindah.
+- Tidak perlu menavigasi 3-4 layer hanya untuk melacak satu user story.
+- Batas natural untuk ekstraksi microservice.
+
+### Prinsip Clean Code
+
+#### Fungsi
+- Lakukan satu hal dan lakukan dengan baik.
+- Nama deskriptif: `getUsersByWorkspace()` bukan `getData()`.
+- Tanpa efek samping: fungsi murni dapat diprediksi dan diuji.
+
+#### Penamaan
+- Variabel: frasa kata benda (`jumlahPengguna`, `workspaceAktif`).
+- Fungsi: frasa kata kerja (`ambilPengguna`, `validasiInput`).
+- Boolean: bentuk pertanyaan (`aktif`, `punyaIzin`, `bisaEdit`).
+
+#### Komentar
+- Jangan komen kode buruk — tulis ulang.
+- Tulis kode yang mendokumentasikan dirinya sendiri.
+- Komentar: **mengapa** (niat), bukan apa (jelas dari kode).
+
+#### DRY, YAGNI, KISS
+- **DRY**: Jangan ulangi diri sendiri — ekstrak logika bersama.
+- **YAGNI**: Anda tidak akan membutuhkannya — jangan bangun fitur "untuk jaga-jaga".
+- **KISS**: Tetap sederhana — solusi paling sederhana yang berfungsi biasanya terbaik.
+
+### Code Smell & Refactoring
+Identifikasi dan perbaiki: God Class, Long Method, Feature Envy, Data Clumps, Magic Numbers, Shotgun Surgery, Primitive Obsession.
+
+### Framework Keputusan Arsitektur
+1. **Apa yang berubah bersama?** Organisasikan kode yang berubah bersama.
+2. **Apa yang dapat di-deploy secara independen?** Pisahkan layanan berdasarkan batas deployment.
+3. **Apa yang memiliki kebutuhan scaling berbeda?** Scale secara independen hanya yang membutuhkannya.
+4. **Berapa besar tim?** Microservices menambah overhead — mulai monolith, ekstrak saat diperlukan.