Refactor code structure for improved readability and maintainability

README.md

@@ -32,7 +32,7 @@ yarn install
 cp .env.example .env.local
 
 # 4. Get API keys (optional, but recommended)
-# See: docs/API_KEYS.md
+# See: [docs/02-tecnico/apis.md](docs/02-tecnico/apis.md)
 
 # 5. Run migrations
 cd backend
@@ -70,21 +70,33 @@ quasar/
 │  │  └── controllers/ # Request handlers
 │  └── tests/          # Vitest unit tests (63+ tests)
 │
-├── frontend/          # React + Vite + React Query
+├── frontend/          # React 18 + Vite + TypeScript + TanStack
 │  ├── src/
-│  │  ├── routes/      # Pages (/games, /roms, etc.)
-│  │  ├── components/  # React components (Forms, Dialogs, Cards)
-│  │  └── hooks/       # TanStack Query hooks
-│  └── tests/          # Vitest + React Testing Library (59+ tests)
+│  │  ├── components/  # shadcn/ui components + custom components
+│  │  ├── pages/       # Application pages (Dashboard, Games, etc.)
+│  │  ├── api/         # API services and types
+│  │  ├── query/       # TanStack Query configuration
+│  │  ├── form/        # TanStack Form + Zod configuration
+│  │  ├── router/      # TanStack Router configuration
+│  │  ├── types/       # TypeScript type definitions
+│  │  ├── hooks/       # Custom React hooks
+│  │  ├── lib/         # Utility functions
+│  │  ├── styles/      # Global styles and Tailwind config
+│  │  └── layout/      # Layout components (Header, Sidebar, etc.)
+│  ├── tests/          # Vitest + React Testing Library (59+ tests)
+│  ├── public/         # Static assets
+│  └── index.html      # HTML entry point
 │
 ├── tests/
 │  ├── e2e/           # Playwright E2E tests (15 tests)
 │  └── *.spec.ts      # Config validation tests
 │
 ├── docs/             # Documentation
-│  ├── API_KEYS.md    # How to get API credentials
-│  ├── SECURITY.md    # Security guidelines
-│  └── ...
+│  ├── README.md      # Documentation index
+│  ├── 01-conceptos/  # Fundamental concepts and requirements
+│  ├── 02-tecnico/   # Technical documentation
+│  ├── 03-analisis/  # Comparative analysis
+│  └── 04-operaciones/ # Operations and deployment
 │
 ├── .gitea/
 │  └── workflows/
@@ -103,7 +115,7 @@ Copy `.env.example` to `.env.local` (or `.env.development`) and fill in:
 # Database (local SQLite)
 DATABASE_URL="file:./dev.db"
 
-# API Keys (get from docs/API_KEYS.md)
+# API Keys (get from [docs/02-tecnico/apis.md](docs/02-tecnico/apis.md))
 IGDB_CLIENT_ID=your_client_id
 IGDB_CLIENT_SECRET=your_client_secret
 RAWG_API_KEY=your_api_key
@@ -115,10 +127,12 @@ PORT=3000
 LOG_LEVEL=debug
 ```
 
-For production, use Gitea Secrets. See **SECURITY.md** and **docs/API_KEYS.md**.
+For production, use Gitea Secrets. See **SECURITY.md** and **[docs/02-tecnico/apis.md](docs/02-tecnico/apis.md)**.
 
 ## Testing
 
+### General Tests
+
 ```bash
 # Run all tests (unit + config)
 yarn test
@@ -139,6 +153,97 @@ yarn lint
 yarn format
 ```
 
+### Frontend Development and Testing
+
+```bash
+# Navigate to frontend directory
+cd frontend
+
+# Install dependencies
+yarn install
+
+# Start development server
+yarn dev
+# Frontend will be available at: http://localhost:5173
+
+# Build for production
+yarn build
+
+# Preview production build
+yarn preview
+
+# Run frontend-specific tests
+yarn test
+
+# Run frontend tests with coverage
+yarn test:coverage
+
+# Lint frontend code
+yarn lint
+
+# Format frontend code
+yarn format
+
+# Type check frontend
+yarn type-check
+```
+
+### Backend Development and Testing
+
+```bash
+# Navigate to backend directory
+cd backend
+
+# Install dependencies
+yarn install
+
+# Start development server
+yarn dev
+# Backend API will be available at: http://localhost:3000
+
+# Run backend tests
+yarn test
+
+# Run backend tests with coverage
+yarn test:coverage
+
+# Run specific test file
+yarn test -- gamesController.spec.ts
+
+# Run tests in watch mode
+yarn test:watch
+
+# Lint backend code
+yarn lint
+
+# Format backend code
+yarn format
+
+# Type check backend
+yarn type-check
+
+# Database operations
+yarn prisma:migrate
+yarn prisma:generate
+yarn prisma:studio
+```
+
+### API Testing
+
+```bash
+# Test backend API endpoints
+curl http://localhost:3000/health
+
+# Test games endpoint
+curl http://localhost:3000/api/games
+
+# Test metadata search
+curl "http://localhost:3000/api/metadata/search?q=Mario"
+
+# Test ROM scanning
+curl -X POST http://localhost:3000/api/roms/scan -d '{"path":"/path/to/roms"}'
+```
+
 ## Troubleshooting
 
 ### Backend won't start
@@ -158,7 +263,7 @@ Error: EADDRINUSE: address already in use :::3000
 ### Metadata search returns no results
 
 ```
-→ Check that API keys are correct (docs/API_KEYS.md)
+→ Check that API keys are correct ([docs/02-tecnico/apis.md](docs/02-tecnico/apis.md))
 → Check logs: tail -f backend/logs/*.log
 → Test with: curl http://localhost:3000/api/metadata/search\?q\=Mario
 ```
@@ -172,12 +277,12 @@ Error: EADDRINUSE: address already in use :::3000
 
 ## Architecture
 
-For detailed architecture and decisions, see [docs/architecture.md](docs/architecture.md).
+For detailed architecture and decisions, see [docs/01-conceptos/architecture.md](docs/01-conceptos/architecture.md).
 
 ### Tech Stack
 
 - **Backend:** Node.js, Fastify, Prisma ORM, SQLite, TypeScript
-- **Frontend:** React 18, Vite, TanStack Query, Tailwind CSS, shadcn/ui
+- **Frontend:** React 18, Vite, TypeScript, TanStack Query, TanStack Router, TanStack Form, Zod, Tailwind CSS, shadcn/ui
 - **Testing:** Vitest (unit), Playwright (E2E)
 - **APIs:** IGDB (OAuth), RAWG, TheGamesDB
 
@@ -193,10 +298,13 @@ For security guidelines, see [SECURITY.md](SECURITY.md).
 ## Documentation
 
 - **[SECURITY.md](SECURITY.md)** — Security policies and best practices
-- **[docs/API_KEYS.md](docs/API_KEYS.md)** — How to obtain and configure API credentials
-- **[docs/architecture.md](docs/architecture.md)** — System architecture and design decisions
-- **[docs/data-model.md](docs/data-model.md)** — Database schema and entities
-- **[docs/requirements.md](docs/requirements.md)** — Project requirements and use cases
+- **[docs/README.md](docs/README.md)** — Documentation index and navigation guide
+- **[docs/01-conceptos/requirements.md](docs/01-conceptos/requirements.md)** — Project requirements and use cases
+- **[docs/01-conceptos/architecture.md](docs/01-conceptos/architecture.md)** — System architecture and design decisions
+- **[docs/01-conceptos/data-model.md](docs/01-conceptos/data-model.md)** — Database schema and entities
+- **[docs/02-tecnico/apis.md](docs/02-tecnico/apis.md)** — APIs configuration and integration guide
+- **[docs/02-tecnico/frontend.md](docs/02-tecnico/frontend.md)** — Complete frontend architecture and implementation
+- **[docs/03-analisis/competitive-analysis.md](docs/03-analisis/competitive-analysis.md)** — Market analysis and competitive research
 
 ## Development
 
@@ -251,6 +359,7 @@ MIT (or choose your license)
 
 ---
 
-**Status:** MVP (v1.0.0) — Ready for self-hosted deployment.  
-**Last updated:** 2026-02-12  
+**Status:** MVP (v1.0.0) — Ready for self-hosted deployment.
+**Last updated:** 2026-02-22
 **Test coverage:** 122+ unit tests + 15 E2E tests ✅
+**Documentation:** Reorganized and consolidated ✅