Owopor

A comprehensive financial investment platform enabling users to invest in various packages, manage multiple wallets, and track investment returns with seamless onboarding, KYC verification, and multi-provider authentication.

---

Table of Contents

1. Overview
2. Features
3. Tech Stack
4. Prerequisites
5. Installation
6. Configuration
7. Project Structure
8. Usage
9. Backend API
10. Running Tests & Linting
11. Deployment
12. Contributing
13. License

---

Overview

Owopor is a full-stack investment platform that combines a mobile-first React Native frontend with a robust Go backend. The platform handles the complete user journey from authentication through KYC verification to investment management, with built-in support for risk assessment, multi-wallet systems, and real-time investment tracking.

Core Functionality

• User Management & Authentication — Multi-provider OAuth, JWT-based auth, OTP verification
• KYC Verification — Document capture, submission, and verification workflows
• Investment Management — Package selection, portfolio tracking, returns calculation
• Wallet System — Multi-wallet support (main, investment, savings) with balance tracking
• Bank Account Linking — Secure bank account linking with verification
• Risk Assessment — User profiling questionnaire for investment recommendations
• Notifications — Push notifications, email, and SMS alerts for user updates

---

Features

• ✅ Multi-Platform Support — iOS, Android, and Web via React Native & Expo
• ✅ Secure Authentication — JWT tokens, OAuth2 (Google & GitHub), session management
• ✅ KYC Workflow — Document capture via device camera with verification pipeline
• ✅ Bank Integration — Account linking with OTP verification
• ✅ Investment Packages — Tiered investment options with transparent returns tracking
• ✅ Multi-Wallet Architecture — Segregated wallets with inter-wallet transfers
• ✅ Risk Assessment — Questionnaire-based user profiling and recommendations
• ✅ Responsive UI — Native mobile experience with adaptive layouts
• ✅ Real-time Updates — Live balance and investment return tracking
• ✅ Code Quality — ESLint for frontend, TypeScript strict mode, Prettier formatting

---

Tech Stack

Frontend

Layer	Technology
Framework	React Native 19.1.1 with Expo 54.0.27
Routing	Expo Router 6.0.17 with file-based routing
Language	TypeScript 5.9
State Management	React Hook Form 7.67.0, AsyncStorage
Authentication	Firebase Auth, Expo Auth Session
Navigation	React Navigation 7.1.6 + Bottom Tabs
UI Components	Expo Vector Icons, Expo Blur, Expo Linear Gradient
Media	Expo Camera, Expo Image
Code Quality	ESLint, Prettier, Husky, Commitlint

Backend

Layer	Technology
Language	Go 1.25.4
Server	net/http (standard library)
Database	PostgreSQL with pgx/v5 driver
Authentication	JWT (golang-jwt), OAuth2, Session cookies
Security	golang.org/x/crypto, gorilla/sessions
API	RESTful HTTP endpoints

Infrastructure

• Firebase — User authentication, storage, messaging
• PostgreSQL — Primary data store
• OAuth Providers — Google, GitHub

---

Prerequisites

System Requirements

• macOS/Linux/Windows with Bash or PowerShell terminal
• Node.js 18+ and npm/yarn
• Go 1.25.4 or later
• PostgreSQL 13+ (local or cloud instance)
• Git 2.0+

Additional Tools

For mobile development:

• Xcode (macOS only, for iOS development)
• Android Studio (for Android development)
• Expo CLI (optional; npm install -g expo-cli)

---

Installation and Setup

1. Clone the Repository

git clone https://github.com/BalkyBoy/Owopor.git
cd Owopor

2. Setup Frontend (Client)

cd client
npm install
# or
yarn install

3. Setup Backend (Server)

cd ../server
go mod download
go mod tidy

4. Configure Database

Create a PostgreSQL database and update the connection string:

psql -U postgres
CREATE DATABASE owopor;

---

Configuration

Frontend Environment

Create a .env.local file in the client/ directory with Firebase configuration (already included in firebaseConfig.js):

// client/firebaseConfig.js
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_ID",
  appId: "YOUR_APP_ID",
};

Backend Configuration

Set environment variables before running the server:

export DATABASE_URL="postgres://user:password@localhost:5432/owopor"
export JWT_SECRET="your-jwt-secret-key-change-in-production"
export REFRESH_SECRET="your-refresh-secret-key-change-in-production"
export SESSION_KEY="your-session-key-change-in-production"
export GOOGLE_CLIENT_ID="your-google-oauth-client-id"
export GOOGLE_CLIENT_SECRET="your-google-oauth-client-secret"
export GITHUB_CLIENT_ID="your-github-oauth-client-id"
export GITHUB_CLIENT_SECRET="your-github-oauth-client-secret"

Alternatively, update hardcoded values in server/internal/config/config.go and server/internal/auth/models.go.

OAuth Setup

Google OAuth

1. Go to Google Cloud Console
2. Create a new project
3. Enable Google+ API
4. Create OAuth 2.0 credentials (Web application)
5. Add redirect URI: http://localhost:8080/auth/google/callback
6. Copy Client ID and Secret to environment variables

GitHub OAuth

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Create a new OAuth App
3. Set Authorization callback URL: http://localhost:8080/auth/github/callback
4. Copy Client ID and Secret to environment variables

---

Project Structure

Owopor/
├── client/                         # React Native Expo frontend
│   ├── app/                        # Expo Router application root (file-based routing)
│   │   ├── _layout.tsx            # Root layout with theme & font initialization
│   │   ├── index.tsx              # Landing/home screen
│   │   ├── (auth)/                # Authentication flow screens
│   │   │   ├── _layout.tsx
│   │   │   ├── login.tsx
│   │   │   ├── sign-up.tsx
│   │   │   ├── otp.tsx
│   │   │   └── verification.tsx
│   │   ├── (onboarding)/          # Onboarding flow
│   │   │   ├── _layout.tsx
│   │   │   ├── onboarding.tsx     # Intro screen
│   │   │   ├── onboarding1.tsx
│   │   │   ├── onboarding2.tsx
│   │   │   └── onboarding3.tsx
│   │   ├── (kyc)/                 # KYC verification flow
│   │   │   ├── Capture.tsx        # Document capture via camera
│   │   │   ├── Flow.tsx           # KYC workflow orchestrator
│   │   │   ├── Success.tsx        # Verification success screen
│   │   │   └── Verify.tsx         # Document verification
│   │   ├── (bank)/                # Bank account linking
│   │   │   ├── acount.tsx         # Account details
│   │   │   ├── card.tsx           # Card linking
│   │   │   ├── link.tsx           # Linking workflow
│   │   │   └── OTPVerificationScreen.tsx
│   │   ├── (assesment)/           # Risk assessment questionnaire
│   │   │   ├── stepThree.tsx
│   │   │   ├── stepFour.tsx
│   │   │   └── components/
│   │   ├── (profile)/             # User profile management
│   │   │   ├── profilePhoto.tsx
│   │   │   └── Upload.tsx
│   │   ├── (tabs)/                # Main app tab-based navigation
│   │   │   ├── _layout.tsx        # BottomTabNavigator
│   │   │   ├── Dashboard.tsx      # Main dashboard/home
│   │   │   ├── Assets.tsx         # Investment assets & holdings
│   │   │   ├── Wallets.tsx        # Multi-wallet view
│   │   │   └── Profile.tsx        # User profile tab
│   │   ├── (screens)/             # Additional screens
│   │   │   ├── Menu.tsx
│   │   │   ├── Notifications.tsx
│   │   │   └── Packages.tsx       # Investment packages
│   │   └── (terms)/               # Terms & conditions
│   │       ├── _layout.tsx
│   │       └── terms.tsx
│   ├── components/                # Reusable React components
│   │   ├── AmountInput.tsx
│   │   ├── Checkbox.tsx
│   │   ├── Line.tsx
│   │   ├── ProgressBar.tsx
│   │   ├── QuestionHeader.tsx
│   │   └── ... (other shared components)
│   ├── assets/
│   │   ├── fonts/                 # Custom fonts (ReadexPro)
│   │   └── images/                # App icons, splash screens, adaptive icons
│   ├── firebaseConfig.js          # Firebase initialization
│   ├── package.json               # Frontend dependencies
│   ├── tsconfig.json              # TypeScript configuration
│   ├── eslint.config.js           # ESLint configuration
│   ├── prettier.config.js         # Code formatting rules
│   ├── app.json                   # Expo app configuration
│   ├── eas.json                   # EAS (Expo Application Services) build config
│   └── commitlint.config.js       # Commit message linting
│
├── server/                        # Go backend server
│   ├── cmd/
│   │   └── main.go               # Server entry point, route definitions
│   ├── internal/
│   │   ├── auth/                 # Authentication handlers & middleware
│   │   │   ├── handler_jwt.go    # JWT login, registration, refresh
│   │   │   ├── handler_oauth.go  # OAuth2 handlers (Google, GitHub)
│   │   │   ├── handler_session.go # Session-based auth
│   │   │   ├── middleware.go     # JWT verification middleware
│   │   │   ├── models.go         # Auth data models
│   │   │   ├── store.go          # User storage/database logic
│   │   │   └── utils.go          # Auth utilities (token generation, validation)
│   │   ├── config/               # Configuration & constants
│   │   │   └── config.go         # OAuth credentials, JWT secrets
│   │   └── database/             # Database connection
│   │       └── postgres.go       # PostgreSQL pool management
│   ├── go.mod                    # Go module definition
│   └── go.sum                    # Go dependency checksums
│
├── BACKEND_ARCHITECTURE.md       # Detailed backend architecture documentation
└── README.md                      # This file

---

Usage

Running the Frontend

From the client/ directory:

# Start the Expo development server (opens menu for platform selection)
npm start

# Run on iOS (macOS only)
npm run ios

# Run on Android
npm run android

# Run on Web
npm run web

Development Server:

• Press i for iOS simulator
• Press a for Android emulator
• Press w for web browser
• Scan QR code with Expo Go app on physical device

Running the Backend

From the server/ directory:

# Run the server
go run ./cmd/main.go

The server will start on http://localhost:8080

🚀 Complete Auth System running on :8080

Running Code Quality Tools

From the client/ directory:

# Lint the code
npm run lint

# Auto-fix linting issues
npm run lint -- --fix

# Format code with Prettier
npm run format

# Prepare Git hooks (pre-commit linting)
npm run prepare

---

Backend API

Authentication Endpoints

Method	Endpoint	Description	Body
POST	/auth/register	Register new user	{ email, password, name }
POST	/login	JWT login	{ email, password }
POST	/refresh	Refresh JWT token	{ refresh_token }
POST	/forgot-password	Initiate password reset	{ email }
POST	/reset-password	Complete password reset	{ token, new_password }
GET	/protected	Verify JWT (middleware test)	Headers: Authorization: Bearer <token>
GET	/me	Get current user info	Headers: Authorization: Bearer <token>

Session-Based Auth Endpoints

Method	Endpoint	Description
POST	/session/login	Login with session cookie
POST	/session/logout	Logout and clear session
GET	/session/protected	Protected endpoint (session required)

OAuth Endpoints

Method	Endpoint	Description
GET	/auth/google	Initiate Google OAuth flow
GET	/auth/google/callback	Google OAuth redirect URI
GET	/auth/github	Initiate GitHub OAuth flow
GET	/auth/github/callback	GitHub OAuth redirect URI

Authentication

JWT Bearer Token:

curl -H "Authorization: Bearer <your-jwt-token>" http://localhost:8080/protected

Request Example:

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secure123","name":"John Doe"}'

---

Running Tests & Linting

Frontend

# Run ESLint
npm run lint

# Format code
npm run format

# Check TypeScript types
npx tsc --noEmit

Backend

cd ../server

# Run tests (if test suite exists)
go test ./...

# Run with verbose output
go test -v ./...

# Format code
go fmt ./...

# Lint with golangci-lint (if installed)
golangci-lint run ./...

# Check for security vulnerabilities
go list -json ./... | nancy sleuth

---

Deployment

Frontend Deployment

EAS CLI (Recommended for Expo)

npm install -g eas-cli

# Log in to Expo
eas login

# Build for iOS
eas build --platform ios

# Build for Android
eas build --platform android

# Submit to app stores
eas submit --platform ios
eas submit --platform android

Manual Build

# Create a web build
npm run web

# Deploy the `web-build/` directory to hosting (Vercel, Netlify, etc.)

Backend Deployment

Docker (Recommended)

Create a Dockerfile in the server/ directory:

FROM golang:1.25

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .

RUN go build -o server ./cmd/main.go

EXPOSE 8080

CMD ["./server"]

Build and run:

docker build -t owopor-server .
docker run -e DATABASE_URL="..." -p 8080:8080 owopor-server

Heroku / Railway / Cloud Run

# Heroku example
git push heroku main

# Set environment variables
heroku config:set DATABASE_URL="postgres://..."
heroku config:set JWT_SECRET="your-secret"

Environment Variables for Production

Always set these in your hosting platform:

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — Strong random string (use openssl rand -hex 32)
• REFRESH_SECRET — Refresh token secret
• SESSION_KEY — Session encryption key
• GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit with conventional commits: git commit -m "feat: add amazing feature"
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Standards

• Frontend: Use TypeScript strict mode, ESLint, Prettier
• Backend: Format with go fmt, pass go vet, use meaningful naming
• Commits: Follow Conventional Commits

Setup Pre-Commit Hooks

cd client
npm run prepare
# This installs Husky & Commitlint to enforce commit standards

---

License

This project is proprietary. All rights reserved.

---

Support & Documentation

For detailed backend architecture, see BACKEND_ARCHITECTURE.md.

For issues, feature requests, or questions, please open an issue on GitHub.