https://github.com/adamsnows/vizinn

An innovative 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.
https://github.com/adamsnows/vizinn

community dev js open python source ts work workflow

Last synced: 5 months ago
JSON representation

Host: GitHub
URL: https://github.com/adamsnows/vizinn
Owner: adamsnows
Created: 2025-03-15T23:59:26.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2025-05-15T15:15:26.000Z (about 1 year ago)
Last Synced: 2025-05-15T15:48:14.203Z (about 1 year ago)
Topics: community, dev, js, open, python, source, ts, work, workflow
Language: TypeScript
Homepage: https://vizinn.com.br
Size: 5.68 MB
Stars: 6
Watchers: 1
Forks: 0
Open Issues: 5
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md

Awesome Lists containing this project

README

**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](https://github.com/adamsnows/vizinn/blob/main/CONTRIBUTING.md) guide.

For information about frontend-backend connectivity, see our [FRONTEND_BACKEND_DOCUMENTATION](https://github.com/adamsnows/vizinn/blob/main/FRONTEND_BACKEND_DOCUMENTATION.md).
### [See or create an issue!](https://github.com/vizinn-app/app/issues)

## 🎨 Design

Check out our design prototype in Figma:
- [Vizinn Design](https://www.figma.com/design/EqwjF3jl0oSDI873mcgwA7/vizinn?node-id=69-7&t=qG45NxpPBtFXYDMH-1)

**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](https://discord.gg/GkfDbTY6xu)**
- 🔗 **[WhatsApp Group](https://chat.whatsapp.com/IkF1YGczvQGL9wxRxp8O7K)**

## 💼 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:
```bash
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:
```bash
git checkout -b feature-name
```
5. **Make your changes** and commit them with clear, descriptive messages:
```bash
git commit -m "Add feature: description of your changes"
```
6. **Push to your fork**:
```bash
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

```bash
# 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

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

```

### Start the Backend

```bash
# 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:

```bash
# Run all services in parallel
npm run dev

```

### Build

```bash
# Build React Native app
pnpm build:app

# Build all packages
pnpm build
```

### Linting and Testing

```bash
# Lint React Native app
pnpm lint:app

# Test React Native app
pnpm test:app
```

## Adding New Dependencies

To add dependencies to a specific package:

```bash
# Example for any package
pnpm --filter add
```

To add development dependencies:

```bash
pnpm --filter add -D
```

## Using Shared Packages

To use shared packages in other projects:

```bash
# Add shared-ui package to any project
pnpm --filter add "shared-ui@workspace:*"
```

## Creating New Shared Packages

Use the available script to easily create new shared packages:

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

## Managing the Backend

The backend uses Poetry for Python dependency management:

```bash
# Inside the packages/backend folder
poetry add

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

For detailed backend setup instructions, see the [backend README](/apps/backend/README.md).

## 🛠️ 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](https://marketplace.visualstudio.com/items?itemName=EthanSK.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:
```bash
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.

```json
{
"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](https://reactnative.dev/docs/getting-started)
- [Expo Documentation](https://docs.expo.dev/)
- [React Navigation Guide](https://reactnavigation.org/docs/getting-started/)
- [NativeWind (TailwindCSS for React Native)](https://www.nativewind.dev/quick-starts/expo)

### FastAPI & Python
- [FastAPI Official Documentation](https://fastapi.tiangolo.com/)
- [SQLAlchemy Tutorial](https://docs.sqlalchemy.org/en/20/tutorial/index.html)
- [Poetry Documentation](https://python-poetry.org/docs/)
- [Python Type Hints Guide](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)

### Monorepo & pnpm
- [pnpm Workspace Guide](https://pnpm.io/workspaces)
- [Monorepo Best Practices](https://monorepo.tools/)

### Development Workflows
- [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- [Pull Request Best Practices](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/)

## 🚀 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!

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/adamsnows/vizinn

Awesome Lists containing this project

README