diff --git a/README.md b/README.md index cbd7646d..c1f62367 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,86 @@ # Vizzy -**Vizzy** is a community-driven platform for buying, selling, trading, and renting items locally, promoting sustainable and affordable resource sharing. +> Archived full-stack marketplace elevating local buying, selling, trading, and renting for a more circular economy. -### Goals +## Project Status -* Encourage conscious consumption -* Reduce waste through reuse and rental -* Foster community cooperation +This repository is now archived. The production deployment has been shut down, but the codebase remains a reference for our team project that combined user-centric design with a scalable architecture. -### Project Resources +## Overview -* πŸ“Œ [Jira Board](https://basigraphics.atlassian.net/jira/software/projects/VIZZY/boards/1/backlog) -* πŸ“Š [Project Plan (Excel)](https://ipcapt-my.sharepoint.com/:x:/g/personal/nfr_ipca_pt/Eb29k3z-aWRGisXGIZopL6IBy5l5QZjY8SjG1iWQDl6c7w) -* πŸ’» [GitHub Repository](https://github.com/Basiiii/Vizzy) +Vizzy connected neighbourhoods through a community marketplace that balanced affordability with sustainability. We designed the experience for fast browsing, secure transactions, and trustworthy user interactions while keeping the platform simple enough to operate in multiple cities. + +## Demo + + + Vizzy product trailer + + +## Architecture at a Glance + +The system is structured as a modern TypeScript monorepo: + +* **Frontend** – Next.js (App Router) with Tailwind CSS, Radix UI, and server-side rendering for SEO-friendly browsing and dynamic, internationalized layouts. +* **Backend** – NestJS service exposing a REST API with Swagger documentation, JWT-based authentication, input validation via Zod, and background processing with queues and schedulers. +* **Data & Auth** – Supabase handled Postgres storage, role-based access, and token verification. Redis was introduced for caching, throttling, and session workflows to keep responses low-latency. +* **Infrastructure** – Deployed as containerized services with environment-driven configuration and centralized logging through Winston. + +## Highlights + +* End-to-end marketplace flows: listings, wishlists, offers, rentals, and messaging. +* Secure auth lifecycle with Supabase-issued JWTs, refresh tokens, and access revocation hooks. +* Redis-backed caching, rate limiting, and job queues to support surges in local demand. +* Media uploads with image processing pipelines for responsive asset delivery. +* City-aware search, filtering, and localization powered by geocoding APIs. +* Accessibility-first UI with component primitives tested across themes and devices. + +## Tech Stack + +| Layer | Technologies | +| ---------- | ------------ | +| Frontend | Next.js 15, React 19, Tailwind CSS 4, Radix UI, React Hook Form, Zod | +| Backend | NestJS 11, Express 5, Supabase SDK, ioredis, Swagger, Winston | +| Tooling | TypeScript 5, ESLint 9, Prettier, TurboPack dev server | +| Data & Ops | Supabase (Postgres + Auth), Redis, Nodemailer, Geocoding APIs | + +## Quality & Testing + +* Automated unit, integration, and end-to-end suites via Jest with coverage tracking. +* Dedicated performance and load testing against key endpoints to validate Redis caching benefits. +* Linting, type checking, and format enforcement wired into CI to keep pull requests healthy. +* GitHub Actions workflows gate pull requests with linting, test runs, and coverage reporting. + +## Getting Started Locally + +> The hosted instance is no longer active. To explore the project, run it locally. + +1. **Requirements** – Node.js 20+, npm, Redis (local or cloud), Supabase project credentials. +2. **Install dependencies**: + ```bash + npm install + ``` +3. **Configure environment** – Copy the variables from [`backend/vizzy-backend/README.md`](backend/vizzy-backend/README.md) into a `.env` file and supply your Supabase, Redis, and SMTP secrets. +4. **Start the stack**: + ```bash + npm run dev + ``` + This runs the Next.js frontend and NestJS backend concurrently. + +## Repository Structure + +``` +β”œβ”€β”€ frontend/ +β”‚ β”œβ”€β”€ vizzy/ # Next.js application +β”‚ └── README.md # Frontend-specific setup notes +β”œβ”€β”€ backend/ +β”‚ β”œβ”€β”€ vizzy-backend/ # NestJS API service +β”‚ └── README.md # Backend environment and API docs +β”œβ”€β”€ package.json # Monorepo scripts to run both services +└── README.md # You are here +``` + +## Core Contributors + +- [Enrique George Rodrigues](https://github.com/Basiiii) +- [JosΓ© AntΓ³nio da Cunha Alves](https://github.com/zealves99) +- [Diogo Araujo Machado](https://github.com/DiogoMachado04) diff --git a/archive-resources/ESI_PDS_ALM_20242025_01.xlsx b/archive-resources/ESI_PDS_ALM_20242025_01.xlsx new file mode 100644 index 00000000..301c4281 Binary files /dev/null and b/archive-resources/ESI_PDS_ALM_20242025_01.xlsx differ diff --git a/backend/README.md b/backend/README.md index 4128b503..5a451e5d 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,7 +1,36 @@ -# Vizzy Backend +# Vizzy Backend (Archived) -This repository contains the backend services for the Vizzy application. +> Service layer responsible for Vizzy's API, authentication, and integrations. -## Project Structure +## Overview -- `vizzy-backend/` - NestJS backend application +The backend folder hosts the NestJS code that powered the Vizzy marketplace. Although the deployment has been shut down, the implementation is preserved for reference during future portfolio reviews or case studies. + +## Structure + +``` +vizzy-backend/ # NestJS 11 service with modules for auth, marketplace, messaging, etc. +└── README.md # Detailed setup instructions, environment variables, and testing guides +``` + +## Highlights + +* Supabase-backed JWT auth with role-aware guards and refresh token flows. +* Redis caching, throttling, and job queues to keep responses fast under load. +* Swagger docs exposed at `/api` for rapid iteration with frontend and QA teams. + +## Getting Started + +To boot the backend locally: + +1. Install dependencies from this directory: + ```bash + npm install --prefix vizzy-backend + ``` +2. Copy the environment template from `vizzy-backend/README.md` and fill in Supabase, Redis, SMTP, and geocoding credentials. +3. Start the service: + ```bash + npm run start:dev --prefix vizzy-backend + ``` + +Refer to [`vizzy-backend/README.md`](vizzy-backend/README.md) for the full breakdown of modules, scripts, and test suites. diff --git a/backend/vizzy-backend/README.md b/backend/vizzy-backend/README.md index 86cc3e7b..0500faa9 100644 --- a/backend/vizzy-backend/README.md +++ b/backend/vizzy-backend/README.md @@ -1,66 +1,81 @@ -# Vizzy Backend API +# Vizzy Backend API (Archived) -

- Nest Logo -

+> NestJS service powering Vizzy's marketplace workflows, authentication, and integrations. -## Description +## Status -Vizzy Backend API is built with [NestJS](https://github.com/nestjs/nest), a progressive Node.js framework for building efficient and scalable server-side applications. +The backend is no longer deployed, but the codebase remains as a reference for the architecture and patterns we implemented during the Vizzy project. -## Installation +## What This Service Handles -```bash -$ npm install -``` +* RESTful API for marketplace features: listings, rentals, messaging, and wishlists. +* JWT authentication pipeline backed by Supabase roles and refresh tokens. +* Redis caching for hot queries, rate limiting, and background job orchestration. +* Media uploads with Sharp transformations and secure storage hand-offs. +* Swagger/OpenAPI docs exposed via `/api` for consumers and QA. -## Running the app +## Tech Stack -```bash -# development -$ npm run start +| Concern | Tools | +| ----------- | ----- | +| Framework | NestJS 11, Express 5 | +| Data & Auth | Supabase (Postgres + Auth), Redis | +| Messaging | Nodemailer SMTP, Geocoding APIs | +| Observability | Winston logger, Nest Throttler | -# watch mode -$ npm run start:dev +## Local Setup -# production mode -$ npm run start:prod +1. Install dependencies: + ```bash + npm install + ``` +2. Use the template below and copy into `.env` with your Supabase, Redis, and SMTP credentials. +3. Run the server: + ```bash + npm run start:dev + ``` +4. Visit `http://localhost:5000/api` for auto-generated Swagger docs. + +### Environment Variables + +``` +PORT= +FRONTEND_URL= +SUPABASE_URL= +SUPABASE_SERVICE_ROLE_KEY= +SUPABASE_ANON_KEY= +JWT_SECRET= +REDIS_HOST= +REDIS_PORT= +REDIS_PASSWORD= +SMTP_USER= +SMTP_PASSWORD= +GEOCODING_BASE_API_URL= +GEOCODING_API_KEY= ``` -## Test +## Testing ```bash # unit tests -$ npm run test +npm run test -# test coverage -$ npm run test:cov -``` - -## Environment Setup - -Create a `.env` file in the root directory with the following variables: +# integration & e2e suites +npm run test:integration +npm run test:e2e +# coverage report +npm run test:cov ``` -PORT=your-port -FRONTEND_URL=your-frontend-url -SUPABASE_URL=your-supabase-url -SUPABASE_SERVICE_ROLE_KEY=your-service-role-key -SUPABASE_ANON_KEY=your-anon-key -JWT_SECRET=your-secret-key -REDIS_HOST=your-redis-host -REDIS_PORT=your-redis-port -REDIS_PASSWORD=your-redis-password -SMTP_USER=your-smtp-username -SMTP_PASSWORD=your-smtp-password -GEOCODING_BASE_API_URL=your-geocoding-api-base-url -GEOCODING_API_KEY=your-geocoding-api-key -``` - -## API Documentation -When running the server, you can access the Swagger API documentation at: +## Project Layout ``` -http://localhost:5000/api +src/ +β”œβ”€β”€ auth/ # JWT guards, strategies, Supabase integration +β”œβ”€β”€ marketplace/ # Listings, rentals, offers modules +β”œβ”€β”€ messaging/ # Conversations, notifications +β”œβ”€β”€ rate-limit/ # Redis-based throttling +β”œβ”€β”€ common/ # DTOs, interceptors, utils +└── main.ts # Nest bootstrap ``` diff --git a/frontend/README.md b/frontend/README.md index 60e9a03d..4e93adbb 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,17 +1,37 @@ -# Vizzy Frontend +# Vizzy Frontend (Archived) -This directory contains the frontend application for Vizzy, built with Next.js. +> Next.js client powering Vizzy's marketplace experience. -## Project Structure +## Overview -The frontend is organized as follows: +This folder contains the source for Vizzy's user-facing web application. The deployment is retired, but the code remains as a reference implementation of our capstone UI. -- `vizzy/` - The main Next.js application - - `app/` - Application routes and pages - - `components/` - Reusable UI components - - `lib/` - Utility functions, API clients, and services - - `public/` - Static assets +## Structure + +``` +vizzy/ # Next.js 15 application +β”œβ”€β”€ app/ # App Router pages, layouts, and server components +β”œβ”€β”€ components/ # Shared UI primitives +β”œβ”€β”€ lib/ # API clients, services, utilities +└── public/ # Static assets +``` + +## Highlights + +* Server-rendered marketplace flows with authenticated dashboards. +* Localization, theming, and accessibility baked into the component system. +* Tight integration with Supabase-backed APIs for listings, messaging, and rentals. ## Getting Started -To work with the frontend application, navigate to the `vizzy` directory and follow the instructions in its README. +1. Install dependencies and run the dev server from the repo root: + ```bash + npm install + npm run dev + ``` +2. Or work directly in this package: + ```bash + npm install --prefix vizzy + npm run dev --prefix vizzy + ``` +3. See [`vizzy/README.md`](vizzy/README.md) for deeper details on scripts, tech stack, and environment configuration. diff --git a/frontend/vizzy/README.md b/frontend/vizzy/README.md index 9088cea7..9e74b9d8 100644 --- a/frontend/vizzy/README.md +++ b/frontend/vizzy/README.md @@ -1,61 +1,58 @@ -# Vizzy - Community Sharing Platform +# Vizzy Frontend (Archived) -Vizzy is a community platform designed to facilitate buying, selling, trading, and renting items between people in the same community, promoting a practical, economical, and sustainable way to share resources. Through Vizzy, users can acquire second-hand products, exchange items, or even rent tools and other equipment. +> Next.js 15 application delivering Vizzy's responsive marketplace experience. -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +## Status -## Objective +The hosted frontend has been sunset. The code remains a reference for the UI/UX we crafted during the Vizzy project. -The platform aims to create a sharing network within a community where members can benefit from more conscious consumption, saving money and resources while promoting sustainability and cooperation. +## Highlights -## Getting Started - -First, install the dependencies: +* App Router architecture with server-side rendering and route-level layouts. +* Authenticated dashboards, wishlists, and messaging driven by Supabase tokens. +* Geolocation-aware browse and search flows, localized with `next-intl`. +* Accessible component system built with Radix primitives and themed via `next-themes`. -```bash -npm install -``` +## Tech Stack -Then, run the development server: +| Concern | Tools | +| ----------- | ----- | +| Framework | Next.js 15, React 19 | +| Styling | Tailwind CSS 4, Radix UI, class-variance-authority | +| Forms | React Hook Form, Zod | +| Data | Supabase SSR helpers, custom API client | -```bash -npm run dev -``` +## Getting Started -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +1. Install dependencies: + ```bash + npm install + ``` +2. Set the required environment variables (see `.env.example`) to point at a running backend and Supabase instance. +3. Run the development server: + ```bash + npm run dev + ``` +4. Visit `http://localhost:3000` to explore the app. ## Project Structure -- `app/` - Application routes and pages using Next.js App Router -- `components/` - Reusable UI components -- `lib/` - Utility functions and services - - `api/` - API client functions - - `constants/` - Application constants - - `services/` - Service functions - - `utils/` - Utility functions - -## Features - -- Authentication and user management -- Dashboard with data visualization -- Contact management -- Internationalization with next-intl -- Theme support with next-themes +``` +app/ # Routes, layouts, server components +components/ # Shared UI building blocks +lib/ +β”œβ”€β”€ api/ # REST client helpers +β”œβ”€β”€ constants/ # App-wide constants +β”œβ”€β”€ services/ # Domain services and side effects +└── utils/ # Misc utilities +public/ # Static assets +``` ## Scripts -- `npm run dev` - Start the development server with Turbopack -- `npm run build` - Build the application for production -- `npm run start` - Start the production server on port 4000 -- `npm run lint` - Run ESLint to check code quality - -## Technologies - -- Next.js 15 -- React 19 -- TypeScript -- Tailwind CSS -- Shadcn UI -- Recharts for data visualization -- Zod for schema validation -- React Hook Form for form handling +```bash +npm run dev # Start dev server with Turbopack +npm run build # Build for production +npm run start # Run production build (default port 4000) +npm run lint # ESLint checks +```