# 02QUEST — Bank & Vote Consensus

**Mobile-first decentralized banking and public voting platform**  
Created by **Joaquim Pedro** (Joaquim Pedro de Morais Filho)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Mobile%20Web-black)](#)
[![Stack](https://img.shields.io/badge/Stack-HTML%20%7C%20Tailwind%20%7C%20Ethers.js%20%7C%20OpenQuestDB-blue)](#)

---

## Overview / Visão geral

| English | Português |
|--------|-----------|
| **02QUEST** is a single-page mobile web application that combines an internal token ledger (**QST**), Web3 deposit flows (USDT / BNB Chain), transfers, withdrawals, vouchers, and a **public voting consensus** module. | **02QUEST** é uma aplicação web mobile (SPA) que combina ledger interno de tokens (**QST**), depósitos Web3 (USDT / BNB Chain), transferências, saques, vouchers e um módulo de **votação pública por consenso**. |
| Data sync uses **OpenQuestDB** (JSONBlob + local cache) — no traditional backend server required for the demo architecture. | A sincronização usa **OpenQuestDB** (JSONBlob + cache local) — sem servidor backend clássico na arquitetura de demonstração. |
| Designed exclusively for **mobile** UX (desktop access is blocked by design). | Projetado exclusivamente para **mobile** (acesso desktop bloqueado por design). |

**Developer / Desenvolvedor:** Joaquim Pedro  
**Product name / Nome do produto:** 02QUEST · OpenQuestDB Bank & Vote  

---

## Live documentation site / Site de documentação

Open the bilingual ecosystem guide:

- **English + Português (interactive):** [`docs/index.html`](docs/index.html)
- **English:** [`docs/en/index.html`](docs/en/index.html)
- **Português:** [`docs/pt/index.html`](docs/pt/index.html)

After publishing to GitHub Pages:

```
https://<your-user>.github.io/02quest-vote/
https://<your-user>.github.io/02quest-vote/docs/
```

---

## Repository structure / Estrutura

```
02quest-vote/
├── app/
│   └── index.html          # Full Bank + Vote application (mobile SPA)
├── docs/
│   ├── index.html          # Bilingual landing (EN/PT switcher)
│   ├── en/index.html       # English ecosystem guide
│   └── pt/index.html       # Portuguese ecosystem guide
├── assets/                 # Optional media for docs
├── LICENSE
├── SECURITY.md
└── README.md
```

---

## Ecosystem map / Mapa do ecossistema

```text
┌─────────────────────────────────────────────────────────────┐
│                     02QUEST ECOSYSTEM                       │
│                   by Joaquim Pedro                          │
├─────────────────────────────────────────────────────────────┤
│  Mobile Client (app/index.html)                             │
│  ├── Auth (register / login / guest voting mode)            │
│  ├── Bank: balance QST · transfer · withdraw · buy USDT     │
│  ├── Vote: public consensus polls                           │
│  ├── Web3: Ethers.js · wallet · QR USDT (BEP-20)            │
│  ├── Vouchers & activity logs                               │
│  └── Admin Core (secure local password)                     │
├─────────────────────────────────────────────────────────────┤
│  OpenQuestDB                                                │
│  ├── JSONBlob remote shared store                           │
│  ├── localStorage cache + sync loop                         │
│  └── Firebase-compatible API shim (ref/get/set/…)           │
├─────────────────────────────────────────────────────────────┤
│  Blockchain (optional path)                                 │
│  └── BNB Smart Chain · USDT BEP-20 deposits                 │
└─────────────────────────────────────────────────────────────┘
```

---

## Features / Funcionalidades

### Bank (QST)
- Internal **QST** balance per user identity  
- **Transfer** between accounts  
- **Withdraw** requests with admin approval queue  
- **Buy** flow via USDT transfer to admin wallet + TX verification  
- Voucher mint / redeem  

### Vote (Consensus)
- Public voting view (guest mode allowed for read/vote UX)  
- Live stats via OpenQuestDB `voting_stats`  
- Mobile-only experience for integrity of the intended UX  

### Web3
- Wallet connect (Ethers.js v6)  
- USDT (BEP-20) contract interaction patterns  
- QR code payment deep-links  

### Admin Core
- Hidden trigger (top-left corner)  
- Metrics: users, circulating QST, USDT in, pending withdrawals  
- Process withdrawals (pay / reject + refund)  

---

## Quick start / Início rápido

### 1. Run locally

Any static server works. Examples:

```bash
# Python
cd app
python -m http.server 8080

# Node
npx serve app
```

Open on a **phone** or Chrome DevTools device emulation (width &lt; 768px).  
Desktop browsers show the “Mobile only” blocker by design.

### 2. Admin password (required for production)

The admin password is **not** hardcoded in this public repository.

In the browser console on the app origin:

```js
localStorage.setItem("02quest_admin_pass", "your-strong-password");
location.reload();
```

Default fallback in code: `CHANGE_ME_ADMIN` — **change it before any real use**.

### 3. OpenQuestDB blob

The app uses a JSONBlob id stored in `localStorage` (`02quest_blob_id`) with a default shared blob for demo.  
For an isolated deployment, create your own blob at [jsonblob.com](https://jsonblob.com) and set:

```js
localStorage.setItem("02quest_blob_id", "your-blob-uuid");
```

---

## Tech stack / Stack

| Layer | Technology |
|-------|------------|
| UI | HTML5, Tailwind CSS (CDN), Font Awesome, Google Fonts |
| Logic | Vanilla JavaScript (class `App`) |
| Web3 | Ethers.js 6.7 |
| QR | qrcodejs |
| Crypto helpers | CryptoJS (SHA-256 vouchers) |
| Data | OpenQuestDB (JSONBlob + localStorage) |
| Design | Glassmorphism, Manrope + Syncopate, mobile-first |

---

## Security notes / Notas de segurança

See [SECURITY.md](SECURITY.md).

Important:
- This architecture is ideal for **prototypes, demos, and controlled environments**.  
- A fully public JSON store is **not** a bank-grade custody system.  
- Always rotate admin credentials and isolate blob IDs for production experiments.  
- Never commit real admin passwords or private keys.

---

## Author / Autor

**Joaquim Pedro**  
Full name: Joaquim Pedro de Morais Filho  

02QUEST · OpenQuestDB Bank & Vote Consensus was designed and built as a unified mobile ecosystem for internal ledger operations and public voting UX.

---

## License

MIT License — see [LICENSE](LICENSE).  
Copyright (c) 2026 Joaquim Pedro de Morais Filho

---

## Disclaimer / Aviso

This software is provided for educational and demonstration purposes.  
It does **not** constitute a licensed financial institution, securities offering, or production-grade custody solution. Use at your own risk.