Vizinn is an innovative, open-source platform that connects users in specific regions for buying, selling, and offering services in a practical and secure way. Our goal is to strengthen the local economy and create a reliable environment for transactions between neighbors and nearby communities. We welcome contributors from all backgrounds. Whether you're a seasoned developer or just starting out, this project offers a fantastic opportunity to collaborate and make a real impact.

• 📚 Learn modern technologies in a real-world application
• 👥 Collaborate with a community of developers
• 📝 Build a meaningful addition to your professional portfolio
• 🌐 Make an impact on local communities through technology

We believe in transparent, collaborative development and look forward to your contributions!
For a detailed contribution guide, check out our CONTRIBUTING guide.
For information about frontend-backend connectivity, see our FRONTEND_BACKEND_DOCUMENTATION.

See or create an issue!

🎨 Design

Check out our design prototype in Figma:

• Vizinn Design

Note: The Figma design requires access permission. Please request access and the project owner will manually grant it to you.

👾 Socials

If you wish to support this initiative or be part of the project, contact us:

• 🔗 Discord
• 🔗 WhatsApp Group

💼 Market Impact

Vizinn is poised to transform local economies and community interactions in significant ways:

🌱 Economic Impact

• Stimulate Local Commerce: Reduce economic leakage by keeping transactions within communities
• Empower Small Entrepreneurs: Lower barriers to entry for micro-entrepreneurs and service providers
• Reduce Transport Costs: Minimize logistics expenses by facilitating hyperlocal transactions
• Create New Market Opportunities: Enable service providers to reach customers in their immediate vicinity

👥 Social Impact

• Strengthen Community Bonds: Foster connections between neighbors who might otherwise never interact
• Increase Safety and Trust: Create a verified marketplace with accountability through the rating system
• Reduce Environmental Footprint: Decrease carbon emissions by encouraging local consumption
• Bridge Digital Divide: Provide technological access to local markets for all community members

🚀 Innovation Potential

• Data-Driven Insights: Generate valuable data about local commerce patterns
• Scalable to Different Contexts: Adaptable to various settings from condominiums to university campuses
• Integration with Local Services: Potential to connect with local delivery networks and payment systems
• Community-Led Development: Features can evolve based on specific community needs

By addressing these market gaps, Vizinn represents not just an app but a paradigm shift in how we think about community commerce and neighborhood interactions.

🚀 Initial Focus

• Users can define their area of interest, allowing transactions within their condominium or in strategic locations such as universities, shopping centers, and specific neighborhoods.

📌 Main Features

• ✅ Exclusive Marketplace – Users in nearby regions can post listings and make purchases.
• 🌟 Featured Listings – Users can pay to highlight their listings and increase visibility.
• 📍 Smart Location Filters – Search for products and services within your condominium or specific areas.
• 🔄 Exchange and Donation Area – Encouraging circular economy within communities.
• 🏢 Building Manager Panel – Announcements and event organization.
• ⭐ Ratings and Reputation – Feedback system to increase trust between users.
• 🔒 Security and Moderation – Reporting inappropriate listings and identity validation.
• 💳 Integrated Payment Option – Facilitating secure transactions within the app.
• 📢 Specific Requests – Users can publish specific demands, such as "I want lunch at UFRN."

🛠 Technologies Used

Front-End (TypeScript)

• ⚛ React Native – Framework for building native mobile apps.
• 📱 Expo – Platform for universal React applications.
• 🚀 Ignite – Boilerplate for accelerated development.
• 🎨 NativeWind (TailwindCSS) – Efficient and optimized styling for React Native.
• 🔗 Axios – Efficient HTTP requests.
• 📲 React Navigation – Flexible navigation system.

Back-End (Python)

• ⚡ FastAPI – Modern and high-performance framework for APIs.
• 🗄 SQLAlchemy – ORM for SQL databases.
• 🔐 JWT – Secure authentication.
• 🏦 SQLite/PostgreSQL – Scalable and reliable database.
• 🔧 Alembic – Database migration tool.
• 📊 Pydantic – Data validation and settings management.

Other Technologies

• 🔔 WebSockets for real-time updates.
• 🚀 CI/CD for automated deployment.
• 📦 PNPM for monorepo package management.
• 🐍 Poetry for Python dependency management.

Monorepo Structure

This monorepo contains the following packages:

• apps/backend: Python API with FastAPI
• apps/frontend-app: React Native mobile application
• apps/shared-ui: UI utilities shared between projects

🚀 Contributing

We welcome contributions to the Vizinn project! Contributing to this project not only helps us build something amazing, but also provides you with valuable experience in modern development practices and technologies.

Why Contribute to Vizinn?

• Gain experience with modern tech stack (React Native, FastAPI, etc.)
• Build your portfolio with meaningful open source contributions
• Connect with a community of developers
• Learn collaborative development workflows
• Make a positive impact on local communities

Contribution Workflow

1. Fork the repository to your own GitHub account
2. Clone your fork to your local machine:

   git clone https://github.com/YOUR-USERNAME/vizinn-app.git
   cd vizinn

3. Set up the project by following the installation instructions below
4. Create a branch for your feature or bug fix:

   git checkout -b feature-name

5. Make your changes and commit them with clear, descriptive messages:

   git commit -m "Add feature: description of your changes"

6. Push to your fork:

   git push origin feature-name

7. Open a pull request to the main repository

Contribution Guidelines

• Before starting work, check the issues and existing PRs to avoid duplication
• Follow the code style and conventions used in the project
• Write clear commit messages
• Include tests and documentation for your changes
• Keep PRs focused on a single feature or fix

Becoming a Contributor

Once your PR is accepted:

• You'll be given the "contributor" role on our Discord server
• Your name will be added to our contributors list
• You'll have the opportunity to become a regular maintainer

Requirements

• Node.js >= 18.0.0
• pnpm >= 8.0.0
• Python >= 3.13
• Poetry (for managing backend dependencies)

Installation

# Install monorepo dependencies
pnpm install

# Install backend dependencies (Python)
cd apps/backend
poetry install

Running the Project

To run the Vizinn project, you need to start both the frontend and backend servers. The simplest way is to run these commands in separate terminal windows:

Start the Frontend

# Navigate to the project root and run:
npm run dev:frontend

Start the Backend

# Navigate to the project root and run:
npm run dev:backend

Running Both Together

If you want to run both servers simultaneously, you can use:

# Run all services in parallel
npm run dev

Build

# Build React Native app
pnpm build:app

# Build all packages
pnpm build

Linting and Testing

# Lint React Native app
pnpm lint:app

# Test React Native app
pnpm test:app

Adding New Dependencies

To add dependencies to a specific package:

# Example for any package
pnpm --filter <package-name> add <dependency-name>

To add development dependencies:

pnpm --filter <package-name> add -D <dependency-name>

Using Shared Packages

To use shared packages in other projects:

# Add shared-ui package to any project
pnpm --filter <project-name> add "shared-ui@workspace:*"

Creating New Shared Packages

Use the available script to easily create new shared packages:

./create-shared-package.sh package-name "Package description"

Managing the Backend

The backend uses Poetry for Python dependency management:

# Inside the packages/backend folder
poetry add <package-name>

# Run the FastAPI server
poetry run uvicorn backend.app:app --reload

For detailed backend setup instructions, see the backend README.

🛠️ VS Code Workspace Setup

To enhance your development experience, we provide a VS Code workspace configuration that automatically sets up your project structure and opens multiple terminals for development.

Required Extension

Before using the workspace configuration, install the following VS Code extension:

• Restore Terminals - manuth/vscode-restore-terminals
  • This extension automatically opens and configures your terminal sessions when you open the workspace.

How to Use the Workspace

1. Open the project in VS Code by clicking on the workspace.code-workspace file in the root directory.

2. Alternatively, you can open it from the command line:

   code workspace.code-workspace

3. This will set up your workspace with the following structure:

   • "Vizinn Root" - The root directory of the project
   • "Frontend" - The frontend application
   • "Backend" - The backend API

Automatic Terminal Configuration

With this configuration, when you open the workspace, three terminals will automatically open:

1. App Terminal - Executa o servidor backend (npm run dev:backend)
2. App Server - Executa o aplicativo frontend (npm run dev:frontend)
3. Monorepo Root - Terminal na raiz do projeto para comandos gerais

Workspace Configuration

If you want to customize the workspace configuration, you can edit the workspace.code-workspace file. Here's what the current configuration looks like:

Note: You may need to adjust the file paths in the commands to match your specific project location.

{
  "folders": [
    {
      "path": ".",
      "name": "Vizinn Root"
    },
    {
      "path": "./apps/frontend-app", // Adjust to match current structure
      "name": "Frontend"
    },
    {
      "path": "./apps/backend",
      "name": "Backend"
    }
  ],
  "settings": {
    "restoreTerminals.artificialDelayMilliseconds": 700,
    "restoreTerminals.keepExistingTerminalsOpen": false,
    "restoreTerminals.runOnStartup": true,
    "restoreTerminals.terminals": [
      {
        "splitTerminals": [
          {
            "name": "App Terminal", // Backend Terminal
            "commands": [
              "cd ~/Projects/vizinn",
              "npm run dev:backend" // Starts the FastAPI Server
            ]
          },
          {
            "name": "App Server", // Frontend Terminal
            "commands": [
              "cd ~/Projects/vizinn",
              "npm run dev:frontend" // Starts React Native app with Expo
            ]
          },
          {
            "name": "Monorepo Root", // Additional terminal for other commands
            "commands": [
              "cd ~/Projects/vizinn",
              "git pull"
            ]
          }
        ]
      }
    ]
  }
}

📚 Learning Resources

To help you get started with the technologies used in this project, we've compiled a list of useful resources:

React Native & Expo

• React Native Official Documentation
• Expo Documentation
• React Navigation Guide
• NativeWind (TailwindCSS for React Native)

FastAPI & Python

• FastAPI Official Documentation
• SQLAlchemy Tutorial
• Poetry Documentation
• Python Type Hints Guide

Monorepo & pnpm

• pnpm Workspace Guide
• Monorepo Best Practices

Development Workflows

• GitHub Flow
• Conventional Commits
• Pull Request Best Practices

🚀 Recent Updates

May 18, 2025

• Fixed frontend-backend connectivity issues
• Configured PostgreSQL local database connection
• Resolved CORS configuration issues
• Fixed endpoint URL formats for all API calls (added trailing slashes)
• Created unified documentation for frontend-backend connection
• Increased API timeout for registration process
• Implemented retry mechanism for handling API timeouts
• Added detailed error messages for common connectivity issues

May 14, 2025

• Added comprehensive backend documentation
• Improved monorepo structure and package management
• Added Poetry configuration for Python dependency management
• Enhanced script commands for better development experience
• Updated monorepo package.json with more complete metadata and scripts
• Added Python 3.13 requirement

Transforming Neighborhoods, Connecting People!