docs: update READMEs for microservices split + EdDSA + native control flow#12
Merged
Merged
Conversation
… flow
Both README.md (Spanish) and docs/README_eng.md (English) were stuck on
the pre-refactor state — Angular 20, `apps/back`, single JWT_SECRET,
backend on port 3200 exposed publicly, `*ngIf` performance tips, etc.
Rewritten to reflect the current architecture:
- Architecture: gateway (public, :3100) + api (private, :3200) diagram,
internal-network with `internal: true`.
- Stack: Angular 21, Nx 22, Express 5.2, PostgreSQL 16, esbuild + Vite.
- Project structure: apps/{api, front, gateway} + libs/{rest-dto,
internal-auth}; old `apps/back` removed.
- Scripts: dev:api / dev:gateway / dev:front (instead of dev:back),
build:api / build:gateway, test:api / test:gateway /
test:internal-auth.
- Auth section rewritten around split secrets (JWT_ACCESS_SECRET +
JWT_REFRESH_SECRET), typ + jti claims, refresh_token_family
rotation/reuse detection, and Ed25519 keypair for internal JWT with
link to docs/SECURITY.md.
- Subagent docs: backend developer now mentions
`requireInternalAuth({allowedScopes, requiredPermissions})` rather
than the old `authController.hasPermission`. Frontend developer
notes native control flow (@if / @for / @switch) and no *ngIf /
*ngFor in new code.
- Database section: real schemas straight from db/10.user.sql and
db/20.refresh_token_family.sql instead of the stale toy snippet.
- Env vars: full updated block including INTERNAL_JWT_PRIVATE_KEY /
INTERNAL_JWT_PUBLIC_KEY, GATEWAY_PORT, API_BASE_URL, CORS_ORIGIN.
- Troubleshooting: added the common `refresh_token_family does not
exist` symptom and the dev:db:clean recovery path.
- Roadmap aligned with the SSO/OIDC/SAML/SCIM/multi-tenant direction
discussed in the architecture conversation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ambos
README.md(es) ydocs/README_eng.md(en) estaban anclados al estado pre-refactor. Esta PR los reescribe para reflejar el estado actual del proyecto tras los merges de #9, #10 y #11.Cambios
:3200:3100) → api privado (:3200) conX-Internal-AuthEdDSAapps/{front, back}apps/{front, gateway, api}+libs/{rest-dto, internal-auth}dev:back,build:back,test:backdev:api,dev:gateway,build:api,build:gateway,test:api,test:gateway,test:internal-authtyp+jti,refresh_token_familycon reuse detection, Ed25519 con privilege separation, link adocs/SECURITY.mdJWT_SECRETúnicoJWT_ACCESS_SECRET,JWT_REFRESH_SECRET,INTERNAL_JWT_PRIVATE_KEY/PUBLIC_KEY,GATEWAY_PORT,API_BASE_URLusers.permissionsingulardb/10.user.sqlydb/20.refresh_token_family.sqlauthController.hasPermission(...)requireInternalAuth({allowedScopes, requiredPermissions})delibs/internal-auth*ngFor"@if/@for con track/@switch), sin*ngIf/*ngForen código nuevorefresh_token_family does not existy el path de recoverydev:db:cleanSección de Claude Code / subagentes / skills mantenida (sigue válida), sólo ajustada en los puntos donde la convención del agente cambió (auth en api/gateway, control flow nativo).
Verificación
grep -n 'apps/back' README.md docs/README_eng.md→ 0 ocurrencias.grep -n 'dev:back\|build:back\|test:back\|start:back' README.md docs/README_eng.md→ 0 ocurrencias.grep -n 'JWT_REFRESH_SECRET' README.md docs/README_eng.md→ ahora aparece junto aJWT_ACCESS_SECRET(eran inexistentes / un únicoJWT_SECRETantes).npm run devactualizado a 4 terminales en paralelo (DB + API + Gateway + Frontend).Test plan
docs/README_eng.mdigualmente.docs/SECURITY.md,scripts/rename.sh, etc.) resuelven correctamente.npm run devsin fricción y entiende que tiene que generar las claves Ed25519 antes.No toca código de la aplicación — sólo dos archivos Markdown.
🤖 Generated with Claude Code