Skeleton API First et Mobile First pour démarrer rapidement un projet assisté par IA, basé sur le skeleton officiel API Platform 4.3.

Ce dépôt est un monorepo open source destiné aux développeurs qui souhaitent un point de départ opinioné mais générique. Il fournit :

• api/ — backend Symfony / API Platform (PHP 8.5, FrankenPHP)
• pwa/ — frontend Next.js (MUI)
• une authentification de référence (JWT + SSO Google/Microsoft, vérification email)
• un outillage qualité prêt à l'emploi (PHPStan, php-cs-fixer, Rector, Playwright, pre-push hook)
• une CI/CD GitHub Actions + chart Helm pour Kubernetes

• Stack technique
• Architecture
• Prérequis
• Démarrage rapide (dev)
• Variables d'environnement
• Structure du projet
• Tests
• Outils de qualité
• Outils MCP
• Déploiement
• Documentation complémentaire

L'application est API First : toutes les fonctionnalités sont exposées via l'API REST avant d'être consommées par les clients (application mobile, frontend web). L'expérience utilisateur est pensée Mobile First.

Le site vitrine est pré-rendu côté serveur pour garantir un référencement optimal sur les moteurs de recherche classiques (Google) et les moteurs de réponse IA (GEO — Generative Engine Optimization). L'application métier, protégée par authentification, est rendue côté client pour une expérience interactive fluide.

Le code source du backend suit une architecture DDD organisée par contextes bornés (bounded contexts). Le skeleton fournit le contexte Identity comme exemple de référence ; ajoutez vos propres contextes métier en suivant la même structure.

Le projet utilise le pattern CQRS via Symfony Messenger :

• command.bus — synchrone + asynchrone (écriture, effets de bord)
• query.bus — synchrone uniquement (lecture)

Le skeleton fonctionne en mode mono-tenant par défaut. Le multi-tenant (une base PostgreSQL par client, résolution via JWT ou sous-domaine) est un pattern documenté à implémenter par chaque projet — aucun résolveur de tenant n'est fourni en l'état.

• Docker ≥ 24
• Docker Compose ≥ 2.20
• make (optionnel, pour les raccourcis)

Aucune installation locale de PHP ou Node n'est nécessaire pour le développement.

git clone <repo-url>
cd api-platform-skeleton

cp api/.env api/.env.local
cp pwa/.env.local.example pwa/.env.local
# Éditer les deux fichiers selon votre configuration locale

docker compose run --rm php sh -c "
  mkdir -p config/jwt &&
  openssl genrsa -out config/jwt/private.pem 4096 &&
  openssl rsa -in config/jwt/private.pem -pubout -out config/jwt/public.pem
"

docker compose up -d

git config core.hooksPath .githooks

Services disponibles après démarrage :

docker compose exec php bin/console doctrine:migrations:migrate --no-interaction

curl -k https://localhost/api
# Doit retourner le JSON-LD de l'entrypoint API Platform

api-platform-skeleton/                   # Monorepo (skeleton API Platform 4.3)
├── api/                                 # Backend Symfony / API Platform
│   ├── config/
│   │   ├── jwt/                         # Clés JWT (private.pem, public.pem)
│   │   ├── packages/                    # Config des bundles (doctrine, messenger, security…)
│   │   ├── routes/
│   │   └── services.yaml
│   ├── public/                          # Point d'entrée web (index.php)
│   ├── src/
│   │   ├── Identity/                    # Bounded context d'exemple : utilisateurs & auth
│   │   │   ├── Auth/                    # Controllers SSO + UserProvider + RefreshToken
│   │   │   ├── Entity/                  # User
│   │   │   ├── Event/                   # UserRegistered, EmailVerified
│   │   │   ├── EventListener/           # RateLimitListener, SendVerificationEmailListener
│   │   │   ├── Handler/                 # RegisterUserHandler, VerifyEmailHandler (CQRS — bus Messenger)
│   │   │   ├── Provider/                # MeProvider (API Platform state provider)
│   │   │   ├── Repository/              # UserRepositoryInterface, UserRepository
│   │   │   ├── Resource/                # MeOutput, RegistrationInput/Output, VerifyEmailInput/Output
│   │   │   ├── Type/                    # EmailType, HashedPasswordType, UserIdType, VerificationTokenType
│   │   │   └── ValueObject/             # UserId, Email, HashedPassword, VerificationToken
│   │   ├── Technical/                   # Helpers transverses
│   │   ├── Schedule.php                 # Définition Symfony Scheduler
│   │   ├── Kernel.php
│   │   └── <YourContext>/               # Ajoutez ici vos contextes métier
│   ├── tests/
│   │   ├── Unit/                        # Tests unitaires par bounded context
│   │   └── Integration/                 # Tests d'intégration (Doctrine, Redis…)
│   ├── composer.json
│   ├── phpstan.neon
│   └── .php-cs-fixer.php
├── pwa/                                 # Frontend Next.js — voir pwa/README.md
├── helm/                                # Helm charts Kubernetes (fournis par le skeleton)
├── .github/
│   └── workflows/                       # Pipelines GitHub Actions (CI + déploiement)
└── compose.yaml                         # Docker Compose (fourni par le skeleton)

Convention DDD : les entités du domaine sont des objets PHP avec mapping Doctrine via attributs PHP (pas de fichiers de mapping XML applicatifs).

# Tous les tests
docker compose exec php bin/phpunit

# Par suite
docker compose exec php bin/phpunit --testsuite unit
docker compose exec php bin/phpunit --testsuite integration

# Avec couverture HTML (nécessite Xdebug ou PCOV)
docker compose exec php bin/phpunit --coverage-html var/coverage

# Analyse statique — PHPStan niveau 8
docker compose exec php vendor/bin/phpstan analyse

# Style de code — PSR-12 + règles Symfony
docker compose exec php vendor/bin/php-cs-fixer fix --dry-run --diff
docker compose exec php vendor/bin/php-cs-fixer fix   # correction automatique

# Refactoring automatisé — Rector
docker compose exec php vendor/bin/rector process --dry-run

Le skeleton embarque une configuration Model Context Protocol (mcp.json) qui expose cinq serveurs MCP prêts à l'emploi pour les agents IA (Claude Code, Cursor, etc.).

Les serveurs postgres et redis démarrent automatiquement avec docker compose up. Les serveurs stdio (symfony-ai-mate, context7, mui-mcp) sont lancés à la demande par le client MCP.

Convention : préférez toujours les outils MCP aux commandes CLI brutes (docker compose exec php bin/console …, tail -f var/log/dev.log, etc.). L'agent symfony-ai-mate fournit des équivalents structurés pour la quasi-totalité des commandes courantes.

Pour le détail des outils exposés par chaque serveur, voir api/POSTGRES_MCP.md et api/mate/AGENT_INSTRUCTIONS.md.

Push / Tag
    │
    ├─ Lint & Tests
    │     ├─ PHPStan (analyse statique)
    │     ├─ PHP-CS-Fixer (style)
    │     └─ PHPUnit (unit + integration + contract)
    │
    ├─ Build & Push
    │     └─ Build images Docker (php + pwa) → push vers registry (GHCR)
    │
    └─ Deploy Kubernetes
          ├─ helm upgrade --install api-platform-skeleton ./helm
          └─ kubectl rollout status deployment/api-platform-skeleton-php

Les charts dans helm/ (fournis par le skeleton API Platform et customisés) définissent :

Les secrets sont injectés via envFrom / valueFrom.secretKeyRef — aucune valeur sensible ne doit être committée dans le dépôt.