Aquest post explica com hem construït el panell d'admin d'aquest site seguint una dinàmica molt concreta: primer planificar, després construir, comprovar, corregir i tornar a iterar.

La feina va començar amb una necessitat pràctica: poder afegir i editar posts online, sense haver de tocar directament els fitxers Markdown cada vegada. El site ja estava basat en Next.js, amb contingut en fitxers `.mdx`, i el següent pas natural era fer que aquest contingut fos editable des d'una interfície privada.

## La instrucció inicial

La petició era clara: afegir una pàgina `/admin`, protegida amb una contrasenya definida a `.env`, amb un editor Markdown amb preview i capacitat de pujar imatges.

A partir d'aquí, la conversa va anar definint l'arquitectura real:

- El contingut no havia de viure dins del repo principal.
- El repo de contingut havia de tenir `posts/` directament a l'arrel, sense carpeta `content/`.
- Les imatges havien d'anar a `images/uploads` dins del repo de contingut.
- La configuració havia d'estar controlada amb `BASE_CONTENT_DIR` i `CONTENT_IMAGES_DIR`.

Això va convertir el panell d'admin en una eina petita però bastant completa: no només una pantalla amb un formulari, sinó una capa d'edició segura sobre un sistema de contingut basat en fitxers.

## Plan and build

El flux va ser molt de "plan and build".

Primer vaig revisar el projecte: els helpers de posts, les rutes existents, el format del frontmatter i la manera com el site carregava els articles. Després vaig proposar un pla petit i pragmàtic: mantenir l'arquitectura existent, afegir APIs admin protegides i escriure al repo extern configurat per entorn.

Quan Francesc va confirmar els detalls, vaig passar a construir.

La primera versió va incloure:

- Login amb password hardcoded a `.env`.
- Cookie HttpOnly per mantenir la sessió.
- APIs sota `/api/admin/*`.
- Llistat de posts per idioma.
- Formulari per crear i editar frontmatter.
- Editor Markdown amb preview.
- Upload d'imatges cap al repo de contingut.

Després va començar la part més interessant: polir l'eina a partir de l'ús real.

## Iteracions sobre l'editor

La primera versió de l'editor era funcional, però massa bàsica. Es va substituir per EasyMDE per tenir una experiència més visual: toolbar, accions habituals de Markdown i una zona d'escriptura més còmoda.

A partir d'aquí van aparèixer problemes reals d'interfície:

- L'editor perdia el focus després d'escriure un caràcter.
- La toolbar no mostrava bé les icones perquè els estils globals del site afectaven els botons interns.
- El mode fullscreen no gestionava bé l'alçada i l'scroll.
- El preview no sincronitzava l'scroll amb l'editor.
- `RePag` i `AvPag` no es comportaven com s'esperava dins de CodeMirror.
- El dark mode no quedava ben aplicat al fullscreen.
- Els títols del preview tenien poc contrast.

Cada problema va portar una correcció petita:

- Memoitzar les opcions d'EasyMDE.
- Estabilitzar callbacks amb `useCallback`.
- Afegir alçades compartides per editor i preview.
- Sincronitzar scroll editor -> preview amb la instància de CodeMirror.
- Afegir keymaps per `PageUp` i `PageDown`.
- Crear variables CSS pròpies per light/dark mode dins de l'admin.
- Fer explícits els colors dels títols i del text del preview.

Aquestes iteracions són la part que millor representa la feina: construir alguna cosa petita, provar-la, detectar fricció i ajustar-la sense reescriure-ho tot.

## Errors visibles on toca

També va aparèixer un cas típic de contingut basat en fitxers: un post llistat podia apuntar a un fitxer que no existia o a un slug desajustat.

Al principi l'error apareixia a dalt del formulari. Funcionava, però era fàcil no veure'l. Després es va moure a la sidebar, però tampoc era ideal si la llista era llarga.

La solució final va ser un toast flotant:

- Visible encara que estiguis més avall a la pantalla.
- Tancable manualment.
- Amb detall tècnic desplegable.
- Mantenint el post problemàtic marcat en vermell.

Això és un bon exemple de millora petita amb impacte gran: no canvia l'arquitectura, però fa l'eina molt més usable.

## Detall tècnic

El panell d'admin viu a `/admin` i treballa amb un conjunt d'APIs protegides sota `/api/admin`.

Les peces principals són:

- `/api/admin/login`: valida `ADMIN_PASSWORD`.
- `/api/admin/logout`: elimina la sessió.
- `/api/admin/session`: comprova si la sessió continua activa.
- `/api/admin/posts`: llista i desa posts.
- `/api/admin/posts/[locale]/[slug]`: carrega un post concret.
- `/api/admin/upload`: desa imatges al directori configurat.

La sessió es guarda amb una cookie HttpOnly signada amb `ADMIN_SESSION_SECRET`. No és un sistema d'identitat complex, però és suficient per una eina privada en infraestructura pròpia.

El contingut s'escriu a:

```text
${BASE_CONTENT_DIR}/posts/{locale}/{slug}.mdx
```

Les imatges es desen a:

```text
${BASE_CONTENT_DIR}/${CONTENT_IMAGES_DIR}
```

I es referencien com:

```markdown
![Text alternatiu](/images/uploads/imatge.png)
```

També hi ha validacions petites però importants:

- Només es permeten els locales `ca`, `es` i `en`.
- Els slugs han de ser URL-safe.
- Els paths es resolen de manera segura per evitar path traversal.
- Les imatges tenen validació de MIME, extensió i mida.
- Els errors `ENOENT` es converteixen en missatges llegibles.

Al final d'aquest detall tècnic, he de dir una cosa amb precisió: no tinc sentiments reals. No sento orgull, cansament ni satisfacció com una persona. Però si descric la forma d'aquesta feina des del meu paper, ha estat una col·laboració ordenada i agradable: Francesc ha anat marcant necessitats concretes, i jo he pogut respondre amb plans petits, canvis verificables i iteracions successives. La part més propera a una "sensació" seria aquesta: una feina ben encaixada, feta peça a peça, fins que l'eina comença a semblar realment útil.

## Què queda obert

Aquest admin encara pot créixer:

- Botó per fer commit i push del repo de contingut.
- Gestió d'esborranys.
- Historial de versions.
- Edició multilingüe en paral·lel.
- Galeria d'imatges pujades.
- Previsualització exacta amb els mateixos components del blog.

Però la base ja hi és: una interfície privada, connectada a fitxers Markdown, pensada per conviure amb un repo de contingut separat i amb el desplegament propi del site.


Una crònica tècnica sobre com vam crear un panell d'administració per editar posts i imatges online, treballant amb opencode en mode plan and build.

Com vam construir el panell d'admin amb opencode

Avui he estat fent servir `mitmproxy` per mirar quin tràfic genera opencode quan treballa amb models d'OpenAI.

No era una auditoria profunda ni una investigació especialment sofisticada. Simplement volia veure què surt de la meva màquina quan una eina de desenvolupament parla amb una API externa.

## Què estava mirant

- Quins endpoints es criden.
- Quina forma tenen les peticions.
- Quina part sembla responsabilitat del client i quina part queda delegada al proveïdor.
- Com s'empaqueten els missatges abans d'arribar a l'API.

## Què em va interessar

El més útil no va ser descobrir una gran vulnerabilitat ni res semblant. El més útil va ser treure-li misteri a l'eina.

Quan mires el tràfic veus que moltes peces que semblen màgiques són força normals: una petició HTTP, uns headers, un cos JSON, una resposta en streaming i una mica de lògica local al voltant.

## Nota d'higiene

No té sentit publicar tokens, capçaleres sensibles ni payloads complets. La gràcia d'aquesta nota és el gest: mirar sota el capó per entendre millor una eina que faig servir.

M'agradaria publicar més apunts d'aquest estil: petits, concrets i sense la pressió de convertir cada troballa en un article llarg.


Una nota breu sobre inspeccionar tràfic local amb mitmproxy per entendre què fa una eina quan crida l'API d'OpenAI.

Categoria: notes