Orbit es la app que yo quería para mi propio dinero: cuentas bancarias sincronizadas a través de Open Finance, transacciones organizadas por categoría, gastos fijos, cuentas por pagar y por cobrar, metas, y un asistente que responde preguntas sobre los números en lugar de sobre finanzas en general.
Corre en tres lugares. En la web, como una app de Next.js. En el escritorio, como una app de Tauri para Windows y Linux. En el teléfono, como una app de React Native. Las tres hablan con una sola API en Go y una sola base de datos PostgreSQL, y el código que comparten vive en paquetes dentro del mismo repositorio. El producto tiene dos puertas: un modo local gratuito, donde los datos se quedan en el dispositivo, y un plan pago en la nube, que es lo que paga la sincronización y los servidores.
El repositorio es privado, porque el producto es el código. Lo que puedo mostrar es cómo está armado y por qué. La mayoría de las decisiones de abajo parten de una restricción que estuvo ahí desde el principio: una persona, sin presupuesto, y tres plataformas que tenían que sentirse como la misma app.
El modo local es un producto, no una caché offline
Las apps de escritorio y móviles suelen tratar "sin red" como un estado temporal: una cola de escrituras pendientes, una sincronización cuando vuelve la conexión. Eso nunca fue lo que yo quería. Alguien que no quiere pagar, o que no quiere sus transacciones en el servidor de nadie, igual debería tener una app que funcione, para siempre, sin cuenta.
Decisión
Dos entradas exclusivas. Iniciar sesión significa la nube: la API y PostgreSQL. "Abrir localmente" significa el dispositivo: SQLite dentro de la app de Tauri, SQLite dentro de la app móvil, ninguna petición a la API. Los hooks compartidos no saben con cuál de los dos están hablando: un router local responde las mismas rutas que respondería la API. Migrar de local a la nube es una exportación única, ofrecida cuando la persona vincula una cuenta.
Compromisos
- Cada dominio existe dos veces: una en Go detrás de la API, otra en TypeScript en el router local. Un campo nuevo son dos cambios, y el local es más fácil de olvidar.
- La sincronización bancaria solo existe en la nube. El modo local es carga manual por definición, y la app tiene que decirlo sin que suene a limitación.
- El asistente de IA en modo local depende de un modelo corriendo en la propia máquina de la persona. En el escritorio eso significa Ollama; en el teléfono no hay una forma honesta de ofrecerlo, así que simplemente no está.
Un repositorio, tres cascarones
Tres cascarones, un producto. El panel web de la izquierda es también lo que renderiza el escritorio; el teléfono de la derecha tiene sus propias pantallas sobre los mismos datos.
La app web y la app de escritorio son el mismo producto, y yo no quería mantener dos juegos de pantallas. La app móvil también es el mismo producto, pero no puede renderizar componentes DOM, así que el mismo truco no funciona ahí.
Decisión
Las apps son cascarones delgados. packages/ui guarda las pantallas,
packages/hooks el acceso a datos, packages/lib el cliente de la API, la
sesión y la navegación, y packages/types se genera a partir del archivo
OpenAPI del backend, así que un campo renombrado en Go rompe el build en
TypeScript. Web y escritorio renderizan los mismos componentes; la navegación y
los links se inyectan, porque Next.js y React Router no se ponen de acuerdo en
ninguno de los dos. Móvil comparte hooks, lib y types, y tiene sus propias
pantallas nativas.
Compromisos
- La app móvil es donde la deriva se nota primero. Cuando rediseñé el sistema visual en septiembre, web y escritorio cambiaron juntos y móvil necesitó que tocara cada pantalla a mano.
- Vite en el escritorio y Turbopack en la web leen los mismos paquetes con reglas distintas. Más de una vez un cambio que compilaba en uno rompió el otro, y el arreglo estaba en un archivo de configuración, no en la funcionalidad.
- El build de escritorio fija la dirección de la API en tiempo de compilación. El primer build público apuntaba a
localhost, y nadie lo notó hasta que se instaló en una máquina limpia.
El plan vive en la base de datos, y solo el webhook lo escribe
El acceso a la nube es pago. La forma obvia de restringirlo es revisar el plan en el cliente y ocultar lo que no está incluido. La forma obvia también es la primera que se rompe: el cliente se puede editar, y un plan que vive en el navegador es un plan que cualquiera puede otorgarse a sí mismo.
Decisión
El plan es una columna en el usuario, y el único código que la escribe es el webhook de Stripe. El checkout es la página alojada de Stripe; después de pagar, la app no confía en la redirección: consulta su propia API hasta que el webhook haya cambiado la columna. En el teléfono, el checkout se abre en el navegador del sistema y vuelve a la app mediante un link de retorno; la app entonces hace la misma consulta. Una cuenta sin e-mail confirmado no puede iniciar un checkout, así que los recibos y el portal de facturación siempre tienen a dónde llegar.
Compromisos
- Hay una ventana de unos segundos después de pagar en la que la persona está en una pantalla de "confirmando". La pantalla tiene que explicarlo, o parece rota.
- El desarrollo local necesita la Stripe CLI reenviando webhooks a la máquina. Sin eso el plan nunca cambia, lo cual confunde la primera vez.
- Todo el diseño asume que el webhook llega. Hasta ahora, ha llegado. El día que no llegue, la persona habrá pagado y no tendrá nada, y el arreglo es manual.
El login con Google en el escritorio pasa por el navegador
Google no permite iniciar sesión dentro de un webview embebido, y la app de escritorio es exactamente eso. La app web tuvo inicio de sesión con Google durante semanas mientras el escritorio solo ofrecía e-mail y contraseña, lo que significaba que una cuenta creada con Google no podía entrar al escritorio de ninguna manera.
Decisión
El escritorio genera un secreto, envía su hash a la API para abrir un login pendiente, y abre el navegador del sistema en una página de la app web. Esa página completa el paso de Google y entrega la credencial a la API. El escritorio consulta, demuestra que tiene el secreto, y recibe sus tokens una sola vez. Si el navegador ya tiene una sesión iniciada en Orbit, la página se salta Google y ofrece autorizar el escritorio con esa cuenta, o usar otra.
Compromisos
- Las consultas chocaron con el propio rate limit de la API para las rutas de login: cinco peticiones por minuto, mientras el escritorio preguntaba cada dos segundos. Los primeros usuarios vieron "too many requests" a los veinte segundos. La ruta de reclamo ahora tiene su propio límite, y la app trata un 429 como "espera más", no como un fallo.
- Un login pendiente es una fila en la base de datos con diez minutos de vida. Es una cosa más que limpiar, y un estado más que los tests tienen que cubrir.
- El mismo mecanismo sirve al teléfono, por eso el diseño no se llama "login de escritorio" en ningún lugar que el usuario pueda ver.
Infraestructura que no cuesta nada y se queda dormida
Todo corre en planes gratuitos: la API en Render, la base de datos en Supabase, la web en Vercel, el DNS y un worker en Cloudflare, el código y el CI en GitHub. Los planes gratuitos tienen algo en común: se detienen cuando nadie está mirando. Render pone la API a dormir después de quince minutos sin tráfico y tarda unos veinte segundos en despertarla. Supabase pausa un proyecto después de siete días sin una consulta.
Decisión
Un Cloudflare Worker con dos cron triggers: un ping a la API cada diez minutos,
y una consulta real en cada proyecto de Supabase todas las noches. Guarda el
último estado en KV y publica en un webhook solo cuando un objetivo pasa de ok a
fallando, o al revés. La app web también tiene una pantalla de despertar: el logo
y un spinner mientras la API vuelve, en lugar de un spinner que parece un bug.
Los dominios llegaron después, en un solo lugar: orbit.byjuliocesa.dev para el
sitio y api.orbit.byjuliocesa.dev para la API, ambos bajo un dominio que es
mío, así que cada proyecto recibe un subdominio y las apps nunca necesitan
volver a compilarse cuando cambia el hosting.
Compromisos
- El worker es un repositorio más, un deploy más, y una cosa más que puede detenerse en silencio. El cron tardó más de una hora en empezar a dispararse después del primer deploy, y solo lo supe porque estaba mirando.
- Mantener un servicio gratuito despierto las veinticuatro horas consume la mayor parte de sus horas mensuales. Render da 750; un servicio que nunca duerme usa unas 720.
- El dominio de correo, la dirección de soporte y el nombre comercial en Stripe dependían de tener un dominio. Hasta que compré uno, el e-mail de confirmación solo llegaba a mi propia bandeja de entrada.
Descargas sin token
Los binarios de escritorio estaban adjuntos a GitHub Releases del repositorio privado. Los links públicos a assets de releases privados devuelven 404, así que el sitio tenía una ruta proxy que se autenticaba con un token personal guardado en Vercel y redirigía al asset. Funcionaba en desarrollo y fallaba en producción con un 502 en el instalador de Windows, y acoplaba el sitio a GitHub a través de un secreto que tenía que existir en tiempo de ejecución.
Decisión
Un segundo repositorio, público, que solo guarda releases, sin código:
orbit-releases. El pipeline de
release compila en Windows y Linux, adjunta los cuatro archivos con nombres
estables a ese repositorio, y solo marca el release como latest cuando existen
los cuatro; antes de eso, el link "latest" sigue sirviendo la versión anterior.
El sitio enlaza directo a releases/latest/download/…. Sin proxy, sin token.
Desde
v0.19.0.
Compromisos
- El historial de versiones es público, incluidas las fechas. Nada en él es secreto, pero es visible de una forma en que el código no lo es.
- Una primera versión del pipeline marcaba el release como latest apenas se subía el build de Windows, mientras Linux todavía compilaba. Durante unos veinte minutos los links de Linux dieron 404. Para eso existe ahora el paso de promoción.
- Un repositorio público por app, si hay más apps. La alternativa, un object store con dominio propio, necesita una tarjeta registrada y una alerta de facturación; es el siguiente paso si alguna vez el link de descarga tiene que ser
downloads.something.
Un AppImage que abría en gris
El build de Linux se instalaba bien y abría una ventana sin nada adentro. El log
decía EGL_BAD_PARAMETER y la app seguía corriendo. Ninguna variable de entorno
de WebKit que yo conocía cambió nada.
El empaquetador de AppImage incluye las bibliotecas cliente de Wayland de la imagen de Ubuntu sobre la que compila. Con un Mesa actual, esas bibliotecas no logran crear un display, y WebKit no pinta nada. La misma herramienta además fuerza GDK a X11, así que la app corría bajo XWayland, con un cursor de X y bordes de redimensionado que el compositor nunca pidió.
Decisión
El pipeline desempaqueta el AppImage después de que Tauri lo compila, quita las
bibliotecas de Wayland incluidas, y lo vuelve a empaquetar con el backend nativo
habilitado siempre que WAYLAND_DISPLAY esté presente. El script de instalación
se volvió un instalador de verdad: entrada en el menú, ícono extraído del
AppImage, un comando orbit que abre la app desacoplada, y orbit --update y
orbit --uninstall. La app busca una versión nueva al arrancar y ofrece
actualizar desde la campana de notificaciones. Corregido en
v0.19.2,
actualizador en v0.20.0.
Compromisos
- El arreglo es un
sedsobre un hook de shell dentro de la herramienta de empaquetado de otra persona. Se va a romper el día que ese hook cambie, y el fallo va a ser otra vez una ventana gris. - El paquete
.debusa las bibliotecas del sistema y nunca tuvo el problema. Los usuarios de Debian tienen el camino más limpio; todos los demás reciben el AppImage. - El actualizador en Linux vuelve a ejecutar el script de instalación y reinicia. En Windows descarga el instalador y le pasa el control. Ninguno está firmado, así que ambos muestran las advertencias que muestra el software sin firmar.
Móvil sale de la nube de Expo
La app móvil empezó en Expo con EAS para los builds y las actualizaciones over-the-air. Es el camino más rápido hasta un teléfono. También asume Apple: un build de iOS necesita una Mac y una cuenta de desarrollador, y no tengo ninguna de las dos. El único objetivo realista era Android.
Decisión
Expo se queda como framework; EAS se va. Sin builds en la nube, sin canal OTA, sin cuenta de Expo atada al proyecto. Los builds de Android van a salir de GitHub Actions con Gradle y una clave de firma en los secrets del repositorio, como hace hoy el escritorio, con la primera subida a la Play Store a mano.
Compromisos
- Una actualización al teléfono ahora significa un APK nuevo, no un push silencioso. Es más lento, y también es como funciona cualquier otra app del teléfono.
- Hasta que exista el pipeline de Android, la app móvil vive en el repositorio y en Expo Go en mi propio teléfono. Es la única plataforma sin un build público, por eso este caso no tiene descarga móvil.
- Parte de la infraestructura está dibujada y no construida: Google Play, y una segunda tienda de apps a la que el diseño le guarda un lugar. El diagrama de arriba muestra lo que corre.