hacklab/OASIS_MOBILE
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add CONTEXT folder with project documentation

Browse source
This commit is contained in:
SITO 2026-04-25 16:42:22 +02:00
parent 54ad8a12fc
commit 5ee14d9e1d
5 changed files with 372 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

46
CONTEXT/01_PROYECTO.txt Normal file
View file

@ -0,0 +1,46 @@
===============================================================
OASIS MOBILE — DESCRIPCION DEL PROYECTO
===============================================================
NOMBRE: Oasis Mobile
VERSION APK: 0.6.8 (descompilada en este repo)
REPO REMOTO: http://code.03c8.net:3000/s1to/oasis_mobile.git
USUARIO GITEA: s1to
DESCRIPCION:
Aplicacion movil Android basada en el protocolo SSB (Scuttlebutt).
Red social distribuida/descentralizada con:
- Pubs (nodos de federacion SSB)
- Tribes (comunidades publicas/privadas)
- Wallet ECOin
- Parlamento, Mercado, Trabajos, Tribunales, etc.
STACK TECNICO:
- Android wrapper (Kotlin) con NodeJS embebido via node-on-android
- Backend: Koa.js (Node.js)
- Frontend: Server-Side Rendering con Hyperaxe (sin React/Vue)
- Protocolo: SSB (Secure Scuttlebutt)
- Puerto local de la app: 3000
ESTRUCTURA DEL REPO LOCAL:
/AndroidManifest.xml -> Manifiesto Android (APK descompilada)
/assets/nodejs-project.zip -> ZIP con el proyecto Node.js (fuente real)
/nodejs-project/ -> Proyecto Node.js extraido del ZIP
/nodejs-project/main.js -> Entry point
/nodejs-project/package.json -> Dependencias npm
/nodejs-project/src/
/backend/backend.js -> Router Koa con 100+ rutas (3249 lineas)
/views/ -> Vistas HTML (Hyperaxe SSR)
/models/ -> Modelos de datos (SSB)
/client/assets/styles/ -> CSS
/client/assets/translations/ -> i18n
/configs/ -> Configuracion
RAMAS GIT:
master -> rama principal con todos los commits
test -> rama de pruebas (mismos commits que master)
COMMITS:
9a96d77 first commit (README.md)
f88a179 oasis_mobile 6.9 (APK descompilada)
54ad8a1 feat: add QR codes (implementacion QR)

103
CONTEXT/02_QR_IMPLEMENTACION.txt Normal file
View file

@ -0,0 +1,103 @@
===============================================================
QR CODES — IMPLEMENTACION (commit 54ad8a1)
===============================================================
OBJETIVO:
Añadir QR codes en 3 lugares de la app:
1. Invites de tribes (privados y publicos)
2. Invites de pubs SSB
3. Perfil de usuario (ID SSB como QR para compartir y recibir apoyo)
LIBRERIA USADA:
qrcode ^1.5.4 (ya estaba en package.json, usada en wallet_view.js)
Path de require: require('../server/node_modules/qrcode')
Metodo: QRCode.toString(data, { type: 'svg' }) -> devuelve SVG como string
Render: div({ class: 'qr-code', innerHTML: svgString })
--------------------------------------------------------------
1. TRIBE INVITES — tribes_view.js
--------------------------------------------------------------
ARCHIVO: nodejs-project/nodejs-project/src/views/tribes_view.js
CAMBIOS:
- Añadido: const QRCode = require('../server/node_modules/qrcode');
- renderInvitePage() convertida a async
- Genera QR del inviteCode y lo muestra bajo el texto del codigo
FLUJO:
Backend: POST /tribes/generate-invite
-> tribesModel.generateInvite(tribeId) -> devuelve inviteCode (string)
-> renderInvitePage(inviteCode) -> muestra codigo + QR
Backend ya tenia: ctx.body = await renderInvitePage(...)
ANTES:
exports.renderInvitePage = (inviteCode) => { ... }
DESPUES:
exports.renderInvitePage = async (inviteCode) => {
const qrSvg = inviteCode ? await QRCode.toString(inviteCode, { type: 'svg' }) : '';
// muestra h2 + p con el codigo + div con QR SVG
}
--------------------------------------------------------------
2. PUB INVITES — invites_view.js
--------------------------------------------------------------
ARCHIVO: nodejs-project/nodejs-project/src/views/invites_view.js
CAMBIOS:
- Añadido: const QRCode = require('../server/node_modules/qrcode');
- invitesView() convertida a async
- El bloque snhInvite (caja con invite code del pub) ahora incluye QR
CONTEXTO:
snhInvite se carga desde: src/configs/snh-invite-code.json
Estructura: { name: string, code: string }
El QR se genera del campo snhInvite.code
RUTA: GET /invites -> ctx.body = await invitesView({})
(backend.js linea 1406 ya tenia await)
--------------------------------------------------------------
3. PERFIL DE USUARIO — inhabitants_view.js
--------------------------------------------------------------
ARCHIVO: nodejs-project/nodejs-project/src/views/inhabitants_view.js
CAMBIOS:
- Añadido: const QRCode = require('../server/node_modules/qrcode');
- renderInhabitantCard() convertida a async
-> QR solo se genera para el propio usuario (isMe === true)
-> Aparece debajo del ID SSB en la lista de inhabitants
- inhabitantsView() convertida a async
-> Usa Promise.all() para renderizar las cards async
- inhabitantsProfileView() convertida a async
-> QR se genera SIEMPRE (para cualquier perfil visitado)
-> Aparece en el bloque inhabitant-left junto al avatar y karma
RUTAS:
GET /inhabitants -> inhabitantsView (lista de usuarios)
GET /author/:id -> inhabitantsProfileView (perfil individual)
Ambas ya tenian await en backend.js (lineas 1051 y 1066)
ID SSB formato: @<base64>.ed25519
Ejemplo: @abc123...==.ed25519
--------------------------------------------------------------
4. CSS — style.css
--------------------------------------------------------------
ARCHIVO: nodejs-project/nodejs-project/src/client/assets/styles/style.css
CLASES AÑADIDAS al final del archivo:
.qr-code svg -> max-width 200px, centrado
.qr-code-inline svg -> max-width 140px (en lista inhabitants)
.qr-code-profile svg -> max-width 160px (en perfil)
.user-id-qr -> flex column, para agrupar ID + QR
.user-id-label -> estilo del texto del ID (monospace pequeño)
.invite-code-text -> estilo del codigo de invite (monospace, fondo sutil)
--------------------------------------------------------------
PENDIENTE / POSIBLES MEJORAS:
--------------------------------------------------------------
- Añadir QR tambien en la vista de cada tribe individual (para compartir la URL)
- Permitir escanear QR directamente desde la app (necesita camara nativa)
- Añadir boton "copiar codigo" junto al QR de invite
- QR para pubs individuales en la tabla de pubs activos

64
CONTEXT/03_GIT_ESTADO.txt Normal file
View file

@ -0,0 +1,64 @@
===============================================================
GIT — ESTADO Y COMANDOS
===============================================================
REPO LOCAL: /home/sito/COFRE/CODERS/oasis_mobile/
REMOTE: http://code.03c8.net:3000/s1to/oasis_mobile.git
USUARIO: s1to
ESTADO ACTUAL:
- 3 commits en local (master y test apuntan al mismo sitio)
- Push al remoto PENDIENTE (problema de red)
COMMITS:
9a96d77 first commit
f88a179 oasis_mobile 6.9
54ad8a1 feat: add QR codes for tribe invites, pub invites and user profile sharing
RAMAS:
master -> commit 54ad8a1
test -> commit 54ad8a1 (rama de pruebas)
--------------------------------------------------------------
PROBLEMA DE CONECTIVIDAD AL REMOTO
--------------------------------------------------------------
El servidor code.03c8.net:3000 da TIMEOUT desde esta maquina.
Posibles causas:
- Puerto 3000 bloqueado por firewall en el servidor
- Servidor Gitea caido
- Red privada que requiere VPN
Para diagnosticar (ejecutar en terminal):
nc -zv code.03c8.net 3000 -w 5
Si el servidor es tuyo, abrir puerto:
ufw allow 3000/tcp
Verificar que Gitea corre:
systemctl status gitea
docker ps | grep gitea
--------------------------------------------------------------
COMANDOS PARA CUANDO FUNCIONE LA CONEXION
--------------------------------------------------------------
# Push rama master:
git push -u http://s1to@code.03c8.net:3000/s1to/oasis_mobile.git master
# Push rama test:
git push -u http://s1to@code.03c8.net:3000/s1to/oasis_mobile.git test
# Si la password tiene caracteres especiales (/) usar %2F:
git push -u http://s1to:PASS%2FWORD@code.03c8.net:3000/s1to/oasis_mobile.git master
# Para no repetir credenciales, configurar credential store:
git config --global credential.helper store
git remote set-url origin http://s1to@code.03c8.net:3000/s1to/oasis_mobile.git
--------------------------------------------------------------
WORKFLOW RECOMENDADO
--------------------------------------------------------------
1. Trabajar en rama test
2. Cuando funcione push, subir test primero para verificar
3. Merge a master cuando este todo OK
4. git checkout test -> hacer cambios -> commit -> push origin test

102
CONTEXT/04_ARQUITECTURA.txt Normal file
View file

@ -0,0 +1,102 @@
===============================================================
ARQUITECTURA — OASIS MOBILE (Node.js)
===============================================================
ENTRY POINT:
nodejs-project/nodejs-project/main.js
-> Inicia servidor SSB
-> Arranca backend Koa en puerto 3000
--------------------------------------------------------------
BACKEND (Koa.js)
--------------------------------------------------------------
ARCHIVO: src/backend/backend.js (3249 lineas)
- Router con 100+ rutas GET/POST
- Carga todos los modelos al inicio
- Middleware: validacion host, idioma (cookies), SSB sync status
- Patron: ctx.body = await vistaView(datos)
RUTAS CLAVE:
GET / -> home / feed
GET /inhabitants -> lista de usuarios
GET /author/:id -> perfil de usuario
GET /tribes -> lista de tribes
POST /tribes/generate-invite -> genera invite code de tribe
POST /tribes/join-code -> unirse a tribe con codigo
GET /invites -> pagina de invites/pubs SSB
POST /settings/invite/accept -> aceptar invite de pub SSB
GET /wallet -> wallet ECOin
GET /wallet/receive -> recibir (tiene QR de direccion)
--------------------------------------------------------------
MODELOS (src/models/)
--------------------------------------------------------------
about_model.js -> perfiles de usuario (nombre, foto, descripcion)
tribes_model.js -> tribes: crear, unirse, invites
- generateInvite(tribeId) -> devuelve string con invite code
- joinByInvite(inviteCode) -> une al usuario al tribe
- inviteMode: 'strict' | 'open'
courts_model.js -> sistema de tribunales
banking_model.js -> ECOin wallet
parliament_model.js -> gobernanza
+ 35 modelos mas
--------------------------------------------------------------
VISTAS (src/views/) — Hyperaxe SSR
--------------------------------------------------------------
Patron de uso:
const { div, h2, p, ... } = require('../server/node_modules/hyperaxe');
exports.miVista = async (datos) => {
return template('Titulo', section(div(...)))
}
VISTAS MODIFICADAS (QR):
inhabitants_view.js -> perfil usuario + lista inhabitants
invites_view.js -> invites de pubs SSB
tribes_view.js -> invite page de tribes
wallet_view.js -> (ya tenia QR de direccion ECOin)
OTRAS VISTAS IMPORTANTES:
main_views.js -> template() base con header/footer
feed_view.js -> timeline principal
tribes_view.js -> vistas de tribes (lista, detalle, forms)
banking_views.js -> wallet/banking UI
--------------------------------------------------------------
FRONTEND (CSS/Assets)
--------------------------------------------------------------
src/client/assets/
styles/style.css -> CSS principal (modificado para QR)
styles/mobile.css -> estilos movil
themes/ -> temas visuales
OasisMobile.css -> tema principal de la app
Dark-SNH.css
Matrix-SNH.css
Purple-SNH.css
Clear-SNH.css
translations/ -> ficheros i18n (es, en, ...)
images/ -> imagenes estaticas
--------------------------------------------------------------
SSB (Secure Scuttlebutt)
--------------------------------------------------------------
src/server/SSB_server.js -> servidor SSB
config.keys.id -> ID del usuario actual (@xxx.ed25519)
Identidad SSB: @<base64_ed25519_pubkey>.ed25519
Mensajes SSB: { type, content, ... } firmados con clave privada
Replicacion: via pubs (servidores de federacion)
Pubs: gossip.json en ~/.ssb/gossip.json
Invite codes SSB formato: host:port:@key.ed25519~invite_token
--------------------------------------------------------------
TRIBES vs PUBS
--------------------------------------------------------------
PUB: Servidor SSB de federacion (conectividad de red)
Invite: string "host:port:@key~token"
TRIBE: Comunidad/grupo dentro de la app (social)
Invite: codigo generado por tribesModel.generateInvite()
inviteMode: 'strict' (solo autor) | 'open' (cualquier miembro)

57
CONTEXT/05_PROXIMOS_PASOS.txt Normal file
View file

@ -0,0 +1,57 @@
===============================================================
PROXIMOS PASOS Y TAREAS PENDIENTES
===============================================================
--------------------------------------------------------------
CRITICO — PENDIENTE
--------------------------------------------------------------
[ ] Resolver conectividad al servidor Gitea (code.03c8.net:3000)
-> Comprobar firewall del servidor: ufw allow 3000/tcp
-> Verificar que Gitea corre: systemctl status gitea
-> Una vez conectado: git push -u origin master && git push -u origin test
--------------------------------------------------------------
QR CODES — IMPLEMENTADO (commit 54ad8a1)
--------------------------------------------------------------
[x] QR en invite de tribe (renderInvitePage - tribes_view.js)
[x] QR en invite de pub SSB (snhInvite box - invites_view.js)
[x] QR del ID SSB en perfil de usuario (inhabitants_view.js)
[x] CSS para los QR codes (style.css)
POSIBLES MEJORAS QR:
[ ] QR en vista individual de cada tribe (para compartir URL del tribe)
[ ] Boton "Copiar codigo" junto al QR de invite
[ ] QR para cada pub activo en la tabla de pubs
[ ] QR en la pagina de perfil propio (/settings o similar)
--------------------------------------------------------------
OTRAS FEATURES A EXPLORAR
--------------------------------------------------------------
[ ] Revisar si hay mas vistas donde tenga sentido el QR
[ ] Testing: arrancar la app y verificar que los QR se renderizan
[ ] Revisar tribes_view.js linea 1361 (hay un inviteCode en query param
que tambien podria mostrar QR)
--------------------------------------------------------------
COMO RETOMAR EN NUEVA SESION
--------------------------------------------------------------
1. Abrir este directorio: /home/sito/COFRE/CODERS/oasis_mobile/
2. Leer CONTEXT/01_PROYECTO.txt para orientarse
3. Leer CONTEXT/02_QR_IMPLEMENTACION.txt para ver lo implementado
4. Leer CONTEXT/03_GIT_ESTADO.txt para el estado del repo
5. El codigo fuente esta en:
nodejs-project/nodejs-project/src/
ARCHIVOS MODIFICADOS:
src/views/tribes_view.js
src/views/invites_view.js
src/views/inhabitants_view.js
src/client/assets/styles/style.css
--------------------------------------------------------------
NOTAS
--------------------------------------------------------------
- La APK original esta en: /home/sito/Downloads/oasis-v0.6.8.apk
- El ZIP con el source esta en: assets/nodejs-project.zip
- El source extraido esta en: nodejs-project/nodejs-project/
- Para probar la app hay que tener Node.js + npm install en el proyecto