Skip to content

technical-documentation.md

Latest commit

 

History

History
263 lines (189 loc) · 7.96 KB

technical-documentation.md

File metadata and controls

263 lines (189 loc) · 7.96 KB

📚 Neon Estate - Dokumentacja Techniczna

Last Updated: 2025-12-09 Version: 2.0

📁 Spis Treści

Ten katalog zawiera kompleksową dokumentację techniczną projektu Neon Estate, w tym przewodniki SEO, analizę kodu, narzędzia developerskie oraz instrukcje wdrożenia.

Dostępne Dokumenty:

🔧 Narzędzia Developerskie

  1. guide-mcp-setup.md ⭐

    • Kompletny przewodnik po MCP (Model Context Protocol)
    • Instalacja i konfiguracja Browser MCP (automatyzacja przeglądarki)
    • Instalacja i konfiguracja GitMCP (dostęp do dokumentacji GitHub)
    • Praktyczne przykłady użycia
    • Rozwiązywanie problemów i best practices
    • Start here jeśli chcesz zainstalować MCP

  2. guide-mcp-testing-scenarios.md ⭐

    • 25 gotowych scenariuszy testowych MCP
    • Użycie przez Claude Code chat (najłatwiejsze)
    • Użycie przez skrypty Node.js (automatyzacja)
    • Scenariusze Browser MCP, GitMCP i Combined
    • Instrukcje uruchamiania testów
    • Start here aby przetestować MCP

  3. guide-testing-quickstart.md

    • Quick start guide dla testowania MCP
    • 2 minuty do pierwszego testu
    • Metody testowania: Chat vs Skrypty
    • Wymagania i troubleshooting

📊 SEO & Analytics

  1. guide-seo-configuration.md

    • Complete SEO setup and customization guide
    • 800+ lines of detailed instructions
    • Step-by-step domain change procedures
    • Meta tags and structured data configuration
    • Analytics integration guide

  2. changelog-seo.md

    • Detailed log of all SEO optimizations performed
    • Technical changes summary
    • Performance improvements
    • Files modified list
    • Quality checklist

🔍 Code Review & Analysis

  1. analysis-code-review-website.md

    • Comprehensive code review and analysis
    • Performance, security, accessibility recommendations
    • Implementation roadmap
    • Best practices guidelines

  2. report-backend-implementation.md

    • Summary of backend implementation (AI Atelier)
    • Node.js + Express backend setup
    • Security measures and best practices
    • Deployment guide (Vercel, Heroku, Railway)
    • Technical details of changes made

📋 Zarządzanie Zadaniami

  1. notes-manual-tasks.md
    • Manual tasks and checklists
    • Deployment procedures
    • Testing guidelines
    • Pre-launch checklist

🎯 Quick Start

🆕 For Setting Up Development Tools:

  1. Read guide-mcp-setup.md
  2. Install Browser MCP for browser automation testing
  3. Install GitMCP for AI access to project documentation
  4. Test both servers with /mcp command
  5. Start using MCP in daily development workflow

For New Website Owners:

  1. Read guide-seo-configuration.md
  2. Follow the "Critical SEO Elements to Update" section
  3. Update domain references (search & replace)
  4. Customize meta tags and business information
  5. Use the SEO Checklist before launch
  6. Submit sitemap to Google Search Console

For Developers:

  1. Review analysis-code-review-website.md for code quality standards
  2. Check report-backend-implementation.md for backend features
  3. Review changelog-seo.md for SEO changes
  4. Install MCP servers from guide-mcp-setup.md
  5. Run validation tools and tests before deployment

🔧 Skrypty Developerskie

Projekt zawiera zestaw skryptów pomocniczych w katalogu _scripts/:

Optymalizacja i Build

  1. optimize-images.js

    • Optymalizacja obrazów dla web
    • Konwersja do formatów WebP
    • Kompresja i zmiana rozmiaru
    • Uruchom: node _scripts/optimize-images.js

  2. minify-css.js

    • Minifikacja plików CSS
    • Usuwanie nieużywanego kodu
    • Kompresja dla production
    • Uruchom: node _scripts/minify-css.js

  3. auto-minify-css.js

    • Automatyczna minifikacja CSS przy zapisie
    • Watch mode dla development
    • Uruchom: node _scripts/auto-minify-css.js

Git & Version Control

  1. setup-git-hooks.js
    • Konfiguracja Git hooks
    • Pre-commit checks
    • Automatyczna walidacja
    • Uruchom: node _scripts/setup-git-hooks.js

Testing & MCP

  1. test-runner.js

    • Runner dla wszystkich testów MCP
    • Uruchamianie testów Browser MCP
    • Raportowanie wyników
    • Uruchom: npm test lub node _scripts/test-runner.js

  2. create-all-tests.js

    • Generator skryptów testowych MCP
    • Tworzy 25 gotowych scenariuszy testowych
    • Uruchom: node _scripts/create-all-tests.js

Dokumentacja i Snapshots

  1. snapshot-structure.ps1

    • Generuje snapshot struktury projektu
    • Dokumentacja katalogów i plików
    • Uruchom (PowerShell): .\\_scripts\\snapshot-structure.ps1

  2. snapshot-code.ps1

    • Generuje snapshot kodu projektu
    • Backup przed większymi zmianami
    • Uruchom (PowerShell): .\\_scripts\\snapshot-code.ps1

Dodatkowe Narzędzia

  1. download-sample-images.ps1 / .sh
    • Pobieranie przykładowych obrazów z Unsplash
    • Dostępne dla PowerShell i Bash
    • Uruchom: .\\_scripts\\download-sample-images.ps1 (Windows) lub bash _scripts/download-sample-images.sh (Linux/Mac)

Szczegółowa Dokumentacja Skryptów

Pełna dokumentacja wszystkich skryptów dostępna w: _scripts/README.md

📦 NPM Scripts (Quick Reference)

# Testing
npm test                          # Wszystkie testy MCP
npm run test:browser              # Browser MCP basic test
npm run test:browser:seo          # SEO audit test
npm run test:browser:forms        # Form testing
npm run test:browser:mobile       # Mobile menu test

# Development
npm run dev                       # Start development server
npm start                         # Start production server

# Build & Deploy
npm run build                     # Build dla production
npm run deploy                    # Deploy (wymaga konfiguracji)

🔍 What Was Optimized?

  • ✅ Meta tags (title, description, keywords)
  • ✅ Open Graph & Twitter Cards
  • ✅ Structured Data (Schema.org JSON-LD)
  • ✅ Semantic HTML & Accessibility (ARIA)
  • ✅ Image optimization (local hosting + lazy loading)
  • ✅ Performance (defer JS, DNS prefetch)
  • ✅ Robots.txt & Sitemap.xml
  • ✅ Contact information (clickable links)
  • ✅ Form accessibility

📊 SEO Score

Expected Lighthouse Scores:

  • SEO: 95-100 ✅
  • Accessibility: 95-100 ✅
  • Performance: 85-95 ✅
  • Best Practices: 90-100 ✅

🚀 Quick Reference

Files to Update When Domain Changes:

  1. index.html (20+ locations)

    • Meta tags (lines 21, 25-28, 35-39)
    • Structured data (lines 75-240)

  2. robots.txt (line 10)

  3. sitemap.xml (lines 5, 10-12)

Current Configuration:

  • Domain: neon.estate.com
  • Location: Wrocław, Poland
  • Phone: +48 123 456 789
  • Email: hello@neon.estate

🛠️ Essential Tools

📞 Need Help?

Refer to the detailed guides in this directory or consult:

Documentation maintained by: DominDev SEO Team