docs: update CONTEXT with current state, architecture and Android Studio guide

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SITO 2026-04-29 01:13:52 +02:00
parent b48944ef57
commit ae7f0c1a4a
4 changed files with 209 additions and 152 deletions

View file

@ -3,24 +3,37 @@
===============================================================
NOMBRE: Oasis Mobile
VERSION APK: 0.6.8 (descompilada en este repo)
VERSION APK BASE: 0.6.8 (descompilada en este repo)
VERSION ACTUAL: 6.9 (con todas las mejoras aplicadas)
REPO REMOTO: http://code.03c8.net:3000/s1to/oasis_mobile.git
USUARIO GITEA: s1to
RAMA ACTIVA: test
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.
Red social distribuida/descentralizada - version MAS COMPLETA que el
upstream https://github.com/epsylon/oasis (el local tiene 43 vistas
vs ~15 del upstream publico).
Funcionalidades principales:
- Feed social (posts, comentarios, votos)
- Pubs SSB (nodos de federacion)
- Tribes (comunidades publicas/privadas con inviteLog trazable)
- Wallet ECOin + Transfers + Banking
- Parlamento, Mercado, Trabajos, Tribunales
- Forum, PM (mensajes privados), Agenda, Eventos
- AI integration, Cipher, CV, Documents, Projects
- Blockchain explorer (SSB log como blockchain)
- QR codes para invites y perfiles
- Pixelia (pixel art), Audio, Video, Image
STACK TECNICO:
- Android wrapper (Kotlin) con NodeJS embebido via node-on-android
- Backend: Koa.js (Node.js)
- Backend: Koa.js (Node.js) — backend.js 3249 lineas, 500+ handlers
- Frontend: Server-Side Rendering con Hyperaxe (sin React/Vue)
- Protocolo: SSB (Secure Scuttlebutt)
- Puerto local de la app: 3000
- QR: paquete `qrcode` ^1.5.4
ESTRUCTURA DEL REPO LOCAL:
/AndroidManifest.xml -> Manifiesto Android (APK descompilada)
@ -29,18 +42,28 @@ ESTRUCTURA DEL REPO LOCAL:
/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
/backend/backend.js -> Router Koa (3249 lineas, 500+ rutas)
/views/ -> 43 vistas HTML (Hyperaxe SSR)
/models/ -> Modelos de datos (SSB + custom)
/client/assets/styles/ -> CSS (style.css, mobile.css)
/client/assets/themes/ -> Temas visuales (OasisMobile.css)
/client/assets/translations/ -> i18n
/configs/ -> Configuracion
/configs/ -> Configuracion SSB
RAMAS GIT:
master -> rama principal con todos los commits
test -> rama de pruebas (mismos commits que master)
main -> rama principal
test -> rama de desarrollo activa (todos los commits recientes)
COMMITS:
COMMITS (cronologico):
9a96d77 first commit (README.md)
f88a179 oasis_mobile 6.9 (APK descompilada)
54ad8a1 feat: add QR codes (implementacion QR)
f88a179 oasis_mobile 6.9 (APK descompilada + source extraido)
54ad8a1 feat: add QR codes for tribe invites, pub invites and user profile sharing
5ee14d9 docs: add CONTEXT folder with project documentation
0fc10be feat: invite trazability via inviteLog and pub-invite SSB events
b48944e feat: mobile visual improvements and CSS cleanup
COMPARACION CON UPSTREAM (github.com/epsylon/oasis):
LOCAL > UPSTREAM en casi todo.
El upstream publico tiene ~15 vistas y funcionalidades basicas.
El local tiene 43 vistas, IA, blockchain explorer, tribunales, etc.
NO necesita actualizacion desde upstream — el local es la version avanzada.

View file

@ -1,64 +1,52 @@
===============================================================
GIT — ESTADO Y COMANDOS
GIT — ESTADO (actualizado 2026-04-28)
===============================================================
REPO LOCAL: /home/sito/COFRE/CODERS/oasis_mobile/
REMOTE: http://code.03c8.net:3000/s1to/oasis_mobile.git
USUARIO: s1to
RAMA ACTIVA: test
ESTADO ACTUAL:
- 3 commits en local (master y test apuntan al mismo sitio)
- Push al remoto PENDIENTE (problema de red)
--------------------------------------------------------------
COMMITS ACTUALES (cronologico)
--------------------------------------------------------------
9a96d77 first commit
f88a179 oasis_mobile 6.9 — APK descompilada + source completo
54ad8a1 feat: add QR codes for tribe invites, pub invites and user profile sharing
5ee14d9 docs: add CONTEXT folder with project documentation
0fc10be feat: invite trazability via inviteLog and pub-invite SSB events
b48944e feat: mobile visual improvements and CSS cleanup
COMMITS:
9a96d77 first commit
f88a179 oasis_mobile 6.9
54ad8a1 feat: add QR codes for tribe invites, pub invites and user profile sharing
ESTADO: Working tree clean
RAMAS:
master -> commit 54ad8a1
test -> commit 54ad8a1 (rama de pruebas)
--------------------------------------------------------------
ARCHIVOS MODIFICADOS EN SESIONES DE TRABAJO
--------------------------------------------------------------
src/views/tribes_view.js -> async + QR invite code
src/views/invites_view.js -> async + QR pub invite
src/views/inhabitants_view.js -> async + QR perfil SSB ID
src/views/blockchain_view.js -> filtro invites + renderInviteExtra
src/views/main_views.js -> viewport-fit=cover (notch)
src/models/tribes_model.js -> inviteLog trazabilidad completa
src/models/main_models.js -> publica SSB msg type:pub-invite
src/models/blockchain_model.js -> filtro invites en listBlockchain
src/client/assets/themes/OasisMobile.css -> reescrito limpio (tema color)
src/client/assets/styles/mobile.css -> reescrito completo (480 lineas)
src/client/assets/styles/style.css -> añadidos estilos QR, invites
--------------------------------------------------------------
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:
code.03c8.net:3000 da TIMEOUT desde la maquina de desarrollo.
Diagnostico: nc -zv code.03c8.net 3000 -w 5
Si el servidor es tuyo:
ufw allow 3000/tcp
Verificar que Gitea corre:
systemctl status gitea
docker ps | grep gitea
--------------------------------------------------------------
COMANDOS PARA CUANDO FUNCIONE LA CONEXION
PUSH CUANDO FUNCIONE LA CONEXION
--------------------------------------------------------------
git push -u http://s1to:PASS@code.03c8.net:3000/s1to/oasis_mobile.git test
# 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
NOTA: Si password tiene '/' codificar como '%2F'
Ejemplo: Sito1999/buenacoca -> Sito1999%2Fbuenacoca

View file

@ -10,7 +10,7 @@ ENTRY POINT:
--------------------------------------------------------------
BACKEND (Koa.js)
--------------------------------------------------------------
ARCHIVO: src/backend/backend.js (3249 lineas)
ARCHIVO: src/backend/backend.js (3249 lineas, ~500 handlers)
- Router con 100+ rutas GET/POST
- Carga todos los modelos al inicio
@ -22,81 +22,95 @@ RUTAS CLAVE:
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
POST /tribes/generate-invite -> genera invite code de tribe (con inviteLog)
POST /tribes/join-code -> unirse a tribe con codigo (actualiza inviteLog)
GET /invites -> pagina de invites/pubs SSB
POST /settings/invite/accept -> aceptar invite de pub SSB
POST /settings/invite/accept -> acepta pub invite + publica SSB msg
GET /wallet -> wallet ECOin
GET /wallet/receive -> recibir (tiene QR de direccion)
GET /blockchain -> blockchain explorer (SSB log)
GET /AI -> integracion IA
GET /parliament -> gobernanza
GET /market -> mercado
GET /courts -> tribunales
GET /banking -> banca ECOin
--------------------------------------------------------------
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
about_model.js -> perfiles de usuario
tribes_model.js -> tribes + inviteLog trazabilidad completa
- generateInvite(tribeId) -> registra en inviteLog[] con generatedBy
- joinByInvite(code, userId) -> actualiza inviteLog (status, usedBy, usedAt)
- getTribeById() / listAll() -> exponen inviteLog
main_models.js -> acceptInvite() -> publica SSB msg type:'pub-invite'
blockchain_model.js -> listBlockchain() con filtro 'invites'
courts_model.js, banking_model.js, parliament_model.js, ...
(30+ modelos en total)
--------------------------------------------------------------
VISTAS (src/views/) — Hyperaxe SSR
VISTAS (src/views/) — Hyperaxe SSR — 43 VISTAS TOTALES
--------------------------------------------------------------
Patron de uso:
const { div, h2, p, ... } = require('../server/node_modules/hyperaxe');
exports.miVista = async (datos) => {
return template('Titulo', section(div(...)))
}
Patron:
const { div, h2, p } = require('../server/node_modules/hyperaxe');
exports.miVista = async (datos) => template('Titulo', section(...))
VISTAS MODIFICADAS (QR):
inhabitants_view.js -> perfil usuario + lista inhabitants
invites_view.js -> invites de pubs SSB
tribes_view.js -> invite page de tribes
LISTA COMPLETA DE VISTAS:
activity_view.js, agenda_view.js, AI_view.js, audio_view.js,
banking_views.js, blockchain_view.js, bookmark_view.js,
cipher_view.js, courts_view.js, cv_view.js, document_view.js,
event_view.js, favorites_view.js, feed_view.js, forum_view.js,
image_view.js, indexing_view.js, inhabitants_view.js,
invites_view.js, jobs_view.js, legacy_view.js, main_views.js,
markdown.js, market_view.js, modules_view.js, opinions_view.js,
parliament_view.js, peers_view.js, pixelia_view.js, pm_view.js,
projects_view.js, report_view.js, search_view.js, settings_view.js,
stats_view.js, tags_view.js, task_view.js, transfer_view.js,
trending_view.js, tribes_view.js, video_view.js, vote_view.js,
wallet_view.js
VISTAS CON QR (modificadas):
inhabitants_view.js -> QR del SSB ID en perfil y lista
invites_view.js -> QR del pub invite code
tribes_view.js -> QR del tribe invite code
wallet_view.js -> (ya tenia QR de direccion ECOin)
blockchain_view.js -> renderInviteExtra con detalle de inviteLog
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
--------------------------------------------------------------
BLOCKCHAIN (SSB log como blockchain)
--------------------------------------------------------------
blockchain_model.js -> listBlockchain()
- Llama createLogStream() en todos los mensajes SSB
- Filtra por tipo: 'post', 'about', 'vote', 'tribe',
'pub-invite', 'invites', etc.
- Cada mensaje SSB es un "bloque" con hash, key, sequence, content
blockchain_view.js -> renderBlockchainView()
- Muestra bloques con colores por tipo
- Filtros: ALL, POST, VOTE, TRIBE, INVITES, etc.
- renderInviteExtra(): tabla de inviteLog (6 columnas) para tribes
y tabla de datos pub-invite (pubHost, pubKey, acceptedAt)
--------------------------------------------------------------
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
styles/style.css -> CSS principal (estilos globales)
styles/mobile.css -> 480 lineas para movil (safe-area, touch, QR)
themes/OasisMobile.css -> tema dark gold (color solo, sin mobile)
themes/Dark-SNH.css, Matrix-SNH.css, Purple-SNH.css, Clear-SNH.css
translations/ -> i18n (es, en, ...)
--------------------------------------------------------------
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
Identidad: @<base64_ed25519_pubkey>.ed25519
Mensajes firmados, append-only, cadena de bloques real
Replicacion via pubs (gossip.json en ~/.ssb/)
Pub invite format: host:port:@key.ed25519~invite_token
--------------------------------------------------------------
TRIBES vs PUBS
COMPARACION CON UPSTREAM PUBLICO (github.com/epsylon/oasis)
--------------------------------------------------------------
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)
LOCAL: 43 vistas, AI, blockchain, tribunales, banca, parlamento...
UPSTREAM: ~15 vistas basicas (feed, tribes, about, peers basico)
CONCLUSION: Local es version MAS AVANZADA. NO actualizar desde upstream.

View file

@ -1,57 +1,89 @@
===============================================================
PROXIMOS PASOS Y TAREAS PENDIENTES
PROXIMOS PASOS Y TAREAS PENDIENTES (2026-04-28)
===============================================================
--------------------------------------------------------------
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
-> Comprobar firewall: ufw allow 3000/tcp
-> Verificar Gitea: systemctl status gitea
-> Una vez resuelto: git push -u origin test
--------------------------------------------------------------
QR CODES — IMPLEMENTADO (commit 54ad8a1)
IMPLEMENTADO (commits 54ad8a1, 0fc10be, b48944e)
--------------------------------------------------------------
[x] QR en invite de tribe (renderInvitePage - tribes_view.js)
[x] QR en invite de pub SSB (snhInvite box - invites_view.js)
[x] QR en invite de tribe (tribes_view.js)
[x] QR en invite de pub SSB (invites_view.js)
[x] QR del ID SSB en perfil de usuario (inhabitants_view.js)
[x] CSS para los QR codes (style.css)
[x] inviteLog en tribes con trazabilidad completa (tribes_model.js)
[x] SSB msg type:'pub-invite' al aceptar pub invite (main_models.js)
[x] Filtro 'invites' en blockchain explorer (blockchain_model/view)
[x] renderInviteExtra() con tabla detallada en blockchain_view.js
[x] viewport-fit=cover para notch Android/iOS (main_views.js)
[x] mobile.css completo (480 lineas: safe-area, touch, QR lightbox)
[x] OasisMobile.css limpio (solo theming, sin duplicar mobile.css)
POSIBLES MEJORAS QR:
[ ] QR en vista individual de cada tribe (para compartir URL del tribe)
--------------------------------------------------------------
COMO CORRER EL PROYECTO
--------------------------------------------------------------
LOCALMENTE en tu maquina:
cd /home/sito/COFRE/CODERS/oasis_mobile/nodejs-project/nodejs-project
npm install (si no se ha hecho antes)
node main.js
Abre: http://localhost:3000
EN ANDROID STUDIO:
1. Abrir Android Studio
2. View -> Tool Windows -> Terminal
3. cd <ruta al proyecto>/nodejs-project/nodejs-project
4. node main.js
5. Abrir browser o emulador en http://localhost:3000
ALTERNATIVA (emulador Android):
- Compilar el APK Android que envuelve el Node.js
- El APK usa node-on-android para correr el servidor interno
- Requiere entorno Android SDK configurado
--------------------------------------------------------------
CLAUDE CODE EN ANDROID STUDIO
--------------------------------------------------------------
OPCION 1 (recomendada): JetBrains Plugin
- Android Studio -> Settings -> Plugins -> Marketplace
- Buscar: "Claude Code" o "Anthropic"
- Instalar y reiniciar
- Aparece como panel lateral en el IDE
OPCION 2: Terminal integrada de Android Studio
- View -> Tool Windows -> Terminal
- Ejecutar: claude (si Claude Code CLI esta instalado)
- Claude Code CLI: https://claude.ai/code
OPCION 3: Terminal externa
- Abrir una terminal normal (Konsole, GNOME Terminal)
- cd al proyecto y correr: claude
--------------------------------------------------------------
POSIBLES MEJORAS FUTURAS
--------------------------------------------------------------
[ ] QR en vista individual de cada tribe (para compartir URL)
[ ] 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)
[ ] Testing: arrancar la app y verificar que los QR se renderizan
[ ] Comprobar que inviteLog se persiste correctamente en SSB
--------------------------------------------------------------
OTRAS FEATURES A EXPLORAR
COMPARACION CON UPSTREAM
--------------------------------------------------------------
[ ] 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)
github.com/epsylon/oasis -> version basica (~15 vistas)
Local -> version avanzada (43 vistas, IA, blockchain, etc.)
CONCLUSION: No hay que actualizar desde upstream.
El local ya es mas completo.
--------------------------------------------------------------
COMO RETOMAR EN NUEVA SESION
--------------------------------------------------------------
1. Abrir este directorio: /home/sito/COFRE/CODERS/oasis_mobile/
1. Abrir: /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
3. El codigo esta en: nodejs-project/nodejs-project/src/
4. git log --oneline para ver el estado actual