System Requirements Document

1. Introduction

1.1 Purpose

This System Requirements Document (SRD) defines the complete functional and non-functional requirements for „Stare Stawy — Sąsiedzi”, an ultra-local community web application delivered as an installable Progressive Web App (PWA).

The product is a single, ordered place for the residents of the Stare Stawy housing estate in Oświęcim to ask neighbours for help, lend and borrow items, give things away, find lost property, report local problems, announce important events, find local tradespeople, ask about shared travel, and pass on information about the immediate area.

1.2 Project Name

The working name is „Stare Stawy — Sąsiedzi”. The name may change later; therefore the architecture must not be tightly coupled to this specific name.

1.3 Language

The application interface must be in Polish.

1.4 Scope of This Document

This SRD converts the source project brief into verifiable requirements. It covers the MVP feature modules, user personas, flows, design direction, non-functional requirements, technology stack, and constraints. It replaces any previously generated SRD content.

Page 1 of 51

1.5 Source Content Inventory

Source identity: user-supplied text file containing the project brief/instruction („Polecenie w pliku tekstowym”), attached as chat_media/d3c9ae57-0e65-407c-84b0-8f28f478f987/3581b365_Notes_260923_013110.txt (message 93e984ab-2eff-4ef1-ad30-9e857eef4320, created 2026-09-22T23:34:29.951369+00:00).

Authority: authoritative content source and domain context for the whole build. Its content is the source of truth for the product name, locality, modules, categories, copy, palette, constraints, and quality gate reproduced throughout this SRD.

Page 2 of 51

Named items carried from the source:

Product: „Stare Stawy — Sąsiedzi” — ultra-local community PWA for the residents of the Stare Stawy housing estate in Oświęcim.
Modules: A — Tablica Sąsiadów; B — Pomoc Lokalna; C — Pożyczalnia Rzeczy; D — Alerty Osiedlowe; E — Lokalni Fachowcy; F — Wiadomości; G — Powiadomienia.
Announcement categories: Oddam, Sprzedam, Kupię, Pożyczę, Szukam, Potrzebuję pomocy, Zgubiłem / znaleziono, Pytanie, Informacja, Inne.
Alert categories: Droga / utrudnienia, Awaria, Zwierzę, Zguba / znaleziono, Ważne, Inne.
Professional categories: hydraulik, elektryk, mechanik, fryzjer, kosmetyczka, remonty, ogrodnictwo, transport, inne.
Example tables: profiles, posts, post_categories, comments, messages, conversations, help_requests, borrow_items, alerts, professionals, professional_reviews, reports, blocks, notifications.
Palette: „Sąsiedzka zieleń” ~#2F7D5C, „Ciepły piasek” ~#F7F4EE, card surface ~#FFFFFF, „Grafit” ~#1E1E1E, „Ciepły amber” ~#D9822B.
Copy: headline „STARE STAWY SĄSIEDZI — Twoje osiedle. Twoi sąsiedzi. Jedno miejsce.”; message „Pożycz. Pomóż. Zapytaj. Oddaj. Dowiedz się, co dzieje się obok Ciebie.”; „Bo czasami najlepsza pomoc jest 200 metrów od Ciebie.”; CTAs „Dołącz do Starych Stawów” and „Dołącz bezpłatnie”; empty-state copy „Na razie jest tu spokojnie 👀” and „Bądź pierwszą osobą, która coś doda.”; SEO description „Lokalna społeczność mieszkańców Starych Stawów w Oświęcimiu.”
Demo examples: „Czy ktoś pożyczy wiertarkę?”, „Oddam ubranka dziecięce 92–98.”, „Znaleziono klucze.”, „Czy ktoś jedzie jutro w stronę centrum?”, „Potrzebuję drabiny na sobotę.”, „Zaginął kot.”, „Czy ktoś zna dobrego hydraulika?”.
Environment variables: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (or equivalent current variables).

Page 3 of 51

Media references: the attached text file itself; no other images, logos, or media were supplied.

Unverified facts: the source does not specify a legal entity, contact e-mail/phone, hosting account, or domain; these remain unverified and must not be invented.

2. System Overview

2.1 Problem Statement

Residents of Stare Stawy live very close to one another but have no single, ordered place where they can:

ask neighbours for help,
borrow an item,
give an item away,
find something that was lost,
report a local problem,
announce an important event,
find a local tradesperson,
ask whether anyone is travelling to a given place,
pass on information about the immediate neighbourhood.

Today this information is scattered across Facebook groups, Messenger, WhatsApp, and ad-hoc notices.

2.2 Product Vision

Create one simple place that expresses: „Tutaj dzieje się coś na Starych Stawach.” ("Something is happening at Stare Stawy.")

Page 4 of 51

2.3 Core Product Principle

The application must be:

local,
simple,
fast,
modern,
friendly,
trustworthy,
mobile,
maximally useful.

The application must not become "another Facebook". It must not contain:

a feed stuffed with unnecessary features,
a complicated admin/member panel,
30 categories,
gamification,
artificial "likes",
meaningless rankings.

The most important value: a resident opens the app and immediately sees what is happening in their area.

2.4 Locality Principle

The application is for Stare Stawy in Oświęcim only. It must not be built as a general "portal for all residents of Poland". The whole UX must produce the feeling: „To jest nasze osiedle.” Copy should use expressions such as „na Starych Stawach", „u nas", „sąsiedzi", „Twoja okolica", without over-repeating the estate name.

Page 5 of 51

2.5 Positioning vs. Facebook

The product is an alternative and complement to existing community groups — it does not copy Facebook.

Facebook: big group + chaos + posts.
This application: local needs + ordered categories + proximity + fast answers.

2.6 Delivery Shape

A working, deployable web application (PWA) — not a mockup, not a prototype with stubs, not screens only. Key functions must not be left as TODO. After environment configuration, the app must be runnable and deployable, with a documented Supabase setup, ENV setup, database migrations, local run instructions, and Vercel deployment instructions.

Page 6 of 51

2.7 Delivery Package (ZIP) and Post-Delivery Enhancements

As a system owner, the complete finished project must be delivered to the user as a single downloadable ZIP archive containing the whole runnable project (frontend, shared backend, database migrations/seed, PWA assets, .env.example, and documentation), excluding secrets, node_modules, build output, and other generated artifacts.
As a system owner, the ZIP must be self-contained: after unzipping and configuring the documented environment variables, the project must build, run locally, and be deployable without any file that exists only outside the archive.
As a system owner, the ZIP must include the post-build deliverables listed in Section 3.27 (what was built, how to run, Supabase configuration, ENV configuration, migrations, local run, deployment, ready features, future preparations, limitations).
As a system owner, the ZIP delivery is the first step; after the ZIP is delivered, the site must be enhanced with additional extras („bajery”) that improve the experience without violating the product constraints in Section 2.3 and Section 11.2.
As a system owner, the post-delivery enhancements must stay within the accepted scope: no gamification, no artificial likes, no meaningless rankings, no 30-category taxonomy, no group chat, no complex reservation system, no payments/Stripe, and no weakening of the privacy, location-masking, RLS, or verified-status rules.
As a system owner, the post-delivery enhancements must be additive and must not break the accepted flows, the PWA behaviour, the mobile-first layout, the accessibility requirements, or the quality gate in Section 3.26.

Page 7 of 51

2.8 Provisioned Service Inventory

The runnable system is composed of the following provisioned services, which are the authoritative inventory of infrastructure:

frontend — the React application UI (mobile-first PWA shell, all pages and flows).
backend — one shared FastAPI process that hosts the application APIs and domain modules (board, help, lending, alerts, professionals, messaging, notifications, reports/moderation, admin, uploads). New APIs and domain features are added as routes and modules inside this existing backend, reusing its process, port, dependencies, and deployment; they do not require separate containers or ingress routes.
database — MariaDB for application-owned persistent data (profiles, posts, help requests, lendable items, alerts, professionals and reviews, conversations and messages, reports, blocks, notifications).

The frontend reaches the backend through the application gateway/API layer; the backend is the only service that talks to the database. Supabase Auth, Storage, and Web Push remain external system actors (Section 4.4) and are configured through documented environment variables. This inventory adds no product requirements and does not change any access decision.

3. Functional Requirements

Requirements are expressed as user stories. MVP scope is indicated by the module grouping.

Page 8 of 51

3.1 Module A — Tablica Sąsiadów (Neighbours' Board)

The main feed of the application, where residents publish announcements.

As a resident, I want a main board feed that shows announcements from my neighbourhood, so that I immediately see what is happening nearby.
As a resident, I want to publish an announcement to the board, so that neighbours can see it.
As a resident, I want to assign my announcement to a category chosen from: Oddam, Sprzedam, Kupię, Pożyczę, Szukam, Potrzebuję pomocy, Zgubiłem / znaleziono, Pytanie, Informacja, Inne, so that my post is findable and ordered.
As a resident, I want each announcement to contain a title, description, category, optional photo, publication date, author, approximate location, status, number of replies, and a report option, so that the post is informative and safe.
As a resident, I want to attach an optional photo to my announcement.
As a resident, I want to see the publication date and author on every announcement.
As a resident, I want to see the current status of an announcement.
As a resident, I want to see how many replies an announcement has received.
As a resident, I want to report an announcement that is inappropriate or suspicious.
As a resident, I want the system to never show my exact address publicly — only my approximate location.

Page 9 of 51

3.2 Module B — Pomoc Lokalna (Local Help)

A separate module for requests for help, e.g.:

„Potrzebuję pomocy z wniesieniem szafy."
„Czy ktoś może odebrać mi paczkę?"
„Potrzebuję podwiezienia."
„Czy ktoś ma drabinę?"
„Potrzebuję pomocy przy drobnej naprawie."
As a resident, I want to create a help request, so that neighbours can offer assistance.
As a resident, I want to set a category on my help request.
As a resident, I want to set an urgency level on my help request.
As a resident, I want to set an approximate location for my help request.
As a resident, I want to mark my help problem as resolved, so that others know it no longer needs attention.

Page 10 of 51

3.3 Module C — Pożyczalnia Rzeczy (Item Lending)

Residents list items they are willing to lend (e.g. drill, ladder, washing vacuum, tools, trailer, garden equipment).

As a resident, I want to list an item that I am willing to lend to neighbours.
As a resident, I want each lendable item to record a name, description, photo, owner, approximate location, availability, and lending rules.
As a resident, I want to mark the availability state of an item I have listed.
As a resident, I want to define the lending rules for my item.
As a resident viewing an item, I want a „Napisz do właściciela" action, so that I can contact the owner directly.
As a resident, I want the first version to have no complex reservation system — contacting the owner is sufficient.

Page 11 of 51

3.4 Module D — Alerty Osiedlowe (Neighbourhood Alerts)

A separate section for important local information.

Alert categories: -\x20\xf0\x9f\x9a\xa7 Droga / utrudnienia -\x20\xe2\x9a\xa1 Awaria -\x20\xf0\x9f\x90\x95 Zwierzę -\x20\xf0\x9f\x94\x91 Zguba / znaleziono -\x20\xe2\x9a\xa0️ Ważne -\x20\xf0\x9f\x8c\xb3 Inne

As a resident, I want to view alerts in a dedicated, separate section for important local information.
As a resident, I want to create an alert in a category chosen from Droga / utrudnienia, Awaria, Zwierzę, Zguba / znaleziono, Ważne, Inne.
As a resident, I want an alert to be visually distinguished from an ordinary announcement.
As a resident, I want to report an alert that is incorrect or inappropriate.
As an administrator, I want to approve an alert when approval is required.

Page 12 of 51

3.5 Module E — Lokalni Fachowcy (Local Professionals)

A catalogue of local services.

Professional categories:

hydraulik
elektryk
mechanik
fryzjer
kosmetyczka
remonty
ogrodnictwo
transport
inne

Page 13 of 51

As a resident, I want to browse a catalogue of local services.
As a resident, I want to filter/assign professionals by category, chosen from: hydraulik, elektryk, mechanik, fryzjer, kosmetyczka, remonty, ogrodnictwo, transport, inne.
As a resident, I want a professional profile to display: name, description, category, area of operation, optional phone, optional website, photo/logo, verified status, and reviews.
As a resident, I want an optional phone number and an optional website on a professional profile, so that I can make contact.
As a resident, I want to see a verified status on a professional profile.
As a resident, I want to see and leave reviews for a professional.
As a system/administrator, reviews must be moderatable.
As a system owner, the application must not automatically mark a business as „oszust" (fraudster).
As a system owner, the verified status must never be settable by the user themselves — it is a system/administrator-controlled field.

3.6 Module F — Wiadomości (Messages)

Users can contact one another inside the application.

As a resident, I want a 1:1 conversation with another user.
As a resident, I want a list of my conversations.
As a resident, I want to send and receive messages, each showing a date.
As a resident, I want to see a read status for messages.
As a resident, I want to block another user.
As a resident, I want to report a conversation.
As a system owner, group chat is out of scope for the MVP.

Page 14 of 51

3.7 Module G — Powiadomienia (Notifications)

As a resident, I want to receive notifications about new messages.
As a resident, I want to receive notifications about replies to my announcements.
As a resident, I want to receive notifications about important alerts.
As a resident, I want to receive notifications about activity concerning my own announcements.
As a system owner, the architecture must be prepared for Web Push; where full Web Push requires additional configuration, a complete implementation must be provided together with clear documentation of the required ENV/config.

3.8 Registration and Profile

As a new user, I want to register with e-mail, password, and e-mail confirmation.
As a new user, I want registration to be very simple.
As a system owner, if Supabase Auth is used, it must be used for authentication.
As a user, I want a profile containing: imię / pseudonim, optional photo, optional short description, osiedle, approximate location, and join date.
As a user, I must not be required to publish my full name, exact address, or phone number.

Page 15 of 51

3.9 Location

Location is one of the most important elements of the product.

As a user, I want to optionally share my location with the browser.
As a user, the application must never publicly display my exact coordinates.
As a user, I want to see location expressed as e.g. „~300 m od Ciebie", „Stare Stawy", or „okolice ul. X" instead of „ul. X 17".
As a system owner, safe rounding/masking of location must be implemented.
As a user, I want the application to keep working if I do not share my location.
As a user, I want to manually select „Stare Stawy" as my location.
As a user, I must not be blocked from using the application just because I refused geolocation.

Page 16 of 51

3.10 Main Screen (Główny ekran)

The first screen must immediately answer: „Co dzieje się teraz na Starych Stawach?"

The proposed layout includes:

Header: STARE STAWY — Twoje osiedle. Twoi sąsiedzi.
Search: [\x20\xf0\x9f\x94\x8e Czego szukasz? ]
Add: [ + Dodaj ]
Filter chips: \xf0\x9f\x93\xa2 Wszystko,\x20\xf0\x9f\xa4\x9d Pomoc,\x20\xf0\x9f\x94\xa7 Pożycz,\x20\xf0\x9f\x8e\x81 Oddam,\x20\xf0\x9f\x9a\xa8 Ważne
NAJNOWSCE / NAJNOWSZE section with post cards
Bottom navigation: \xf0\x9f\x8f\xa0 Tablica,\x20\xf0\x9f\xa4\x9d Pomoc,\x20\xf0\x9f\x94\xa7 Pożycz,\x20\xf0\x9f\x92\xac Wiadomości,\x20\xf0\x9f\x91\xa4 Profil
As a resident, I want the main screen to immediately show what is happening now at Stare Stawy.
As a resident, I want quick filter chips (Wszystko, Pomoc, Pożycz, Oddam, Ważne) on the main screen.
As a resident, I want a persistent bottom navigation with Tablica, Pomoc, Pożycz, Wiadomości, Profil.
As a resident, I want a mobile-first layout.

Page 17 of 51

3.11 Adding Content (Dodawanie ogłoszenia)

As a resident, I want a large „+ Dodaj" button.
As a resident, after clicking it I want to choose what to add: [\xf0\x9f\x93\xa2 Ogłoszenie] [\xf0\x9f\xa4\x9d Potrzebuję pomocy] [\xf0\x9f\x94\xa7 Rzecz do pożyczenia] [\xf0\x9f\x9a\xa8 Alert].
As a resident, I want the forms to be short — I must not be forced to fill in 15 fields.

3.12 Search (Wyszukiwanie)

As a resident, I want to search by title, content, and category.
As a resident, I want filters: newest, nearest, category.
As a resident, when my location is available, I want a „W promieniu" filter with 1 km, 3 km, 5 km options.
As a resident, the exact location of people must never be shown.

3.13 Profile (Profil)

As a resident, I want my profile to show: avatar, name/nickname, join date, number of active announcements, reviews (if the review system is deployed), plus „Napisz", „Zablokuj", and „Zgłoś" actions.
As a resident, I do not want private data displayed on a profile.

Page 18 of 51

3.14 Safety and Security

As a resident, I want to report announcements.
As a resident, I want to report users.
As a resident, I want to block users.
As an administrator, I want moderation capabilities.
As an administrator, I want to delete content.
As a system owner, moderation statuses must exist.
As a system owner, rate limiting must be implemented.
As a system owner, spam protection must be implemented.
As a system owner, basic bot protection must be implemented.
As a system owner, data validation must be implemented.
As a system owner, Row Level Security (RLS) must be implemented.
As a system owner, uploads must be secured.
As a system owner, users must not be allowed to set „ZWERYFIKOWANY" themselves — it must be a system/administrator-controlled field.

Page 19 of 51

3.15 Admin Panel

A simple administrator panel, functional rather than pretty.

As an administrator, I want to view users.
As an administrator, I want to block a user.
As an administrator, I want to delete a user.
As an administrator, I want to view announcements.
As an administrator, I want to delete an announcement.
As an administrator, I want to hide an announcement.
As an administrator, I want to view reports.
As an administrator, I want to resolve a report.
As an administrator, I want to approve an alert.
As an administrator, I want to manage professionals.
As an administrator, I want to mark a profile as verified.

3.16 Data Model (Supabase)

As a system owner, I want Supabase Auth, PostgreSQL, Storage, and Row Level Security used where Supabase is the chosen platform.
As a system owner, I want a sensible database schema with example tables: profiles, posts, post_categories, comments, messages, conversations, help_requests, borrow_items, alerts, professionals, professional_reviews, reports, blocks, notifications.
As a system owner, tables must not be created without need.
As a system owner, every table must have sensible id, created_at, updated_at, and where needed user_id, status, deleted_at.
As a system owner, RLS must be enabled.
As a system owner, the system must not rely on frontend-only protection.

Page 20 of 51

3.17 Storage

As a system owner, announcement photos and avatars must be stored in Supabase Storage.
As a system owner, size limits must be applied.
As a system owner, MIME type validation must be enforced.
As a system owner, safe file names must be generated.
As a system owner, a user must be restricted to their own files.

3.18 PWA

As a resident, I want a real PWA with a manifest.
As a resident, I want application icons.
As a resident, I want a theme color.
As a resident, I want an install prompt.
As a resident, I want a service worker.
As a resident, I want basic caching.
As a resident, I want full responsiveness.
As a resident, I want mobile operation, including adding the app to the Android home screen.
As a resident, I want the app to look like a mobile application, not a website shrunk onto a phone.
As a resident, I want a basic offline fallback.

Page 21 of 51

3.19 Landing Page

For a logged-out user, an empty application must not be shown.

As a visitor, I want a landing page with the headline STARE STAWY SĄSIEDZI — Twoje osiedle. Twoi sąsiedzi. Jedno miejsce.
As a visitor, I want a „Dołącz do Starych Stawów" call to action.
As a visitor, I want the message: „Pożycz. Pomóż. Zapytaj. Oddaj. Dowiedz się, co dzieje się obok Ciebie."
As a visitor, I want a „CO MOŻESZ TU ZROBIĆ?" section listing:\x20\xf0\x9f\x94\xa7 Pożyczyć coś od sąsiada;\x20\xf0\x9f\xa4\x9d Poprosić o pomoc;\x20\xf0\x9f\x8e\x81 Oddać rzecz;\x20\xf0\x9f\x9a\xa8 Poinformować o ważnej sprawie;\x20\xf0\x9f\x92\xac Porozmawiać;\x20\xf0\x9f\x9b\xa0️ Znaleźć lokalnego fachowca.
As a visitor, I want the "why" message: „Bo czasami najlepsza pomoc jest 200 metrów od Ciebie."
As a visitor, I want a „Dołącz bezpłatnie" call to action.

3.20 Empty States

As a resident, on an empty screen I want a sensible message such as „Na razie jest tu spokojnie\x20\xf0\x9f\x91\x80" or „Bądź pierwszą osobą, która coś doda." instead of a bare "Brak wyników".
As a resident, every empty screen must have a sensible message and a call to action, e.g. [ Dodaj pierwsze ogłoszenie ].

Page 22 of 51

3.21 Demo Data

As a developer, I want seed/demo data in the development environment.
As a developer, demo entries should include examples such as: „Czy ktoś pożyczy wiertarkę?", „Oddam ubranka dziecięce 92–98.", „Znaleziono klucze.", „Czy ktoś jedzie jutro w stronę centrum?", „Potrzebuję drabiny na sobotę.", „Zaginął kot.", „Czy ktoś zna dobrego hydraulika?".
As a system owner, demo data must be clearly marked as DEMO.
As a system owner, the system must not pretend to be real residents.
As a system owner, the system must not create fake "real" reviews.

3.22 Monetisation (Not Implemented Yet)

As a system owner, monetisation is a future possibility only: business profiles, highlights, local ads, sponsored posts.
As a system owner, Stripe must not be integrated at this stage, unless the architecture requires preparing a placeholder.
As a system owner, the priority is validating whether residents actually use the product.

Page 23 of 51

3.23 Privacy and Legal Pages

As a user, I want a privacy policy as a separate page.
As a user, I want terms of service as a separate page.
As a user, I want a contact page.
As a user, I want the ability to delete my account.
As a user, I want the ability to delete my own content.
As a user, I want the ability to log out.
As a user, I want basic information about data processing.
As a system owner, the application must not collect data it does not need.
As a system owner, special protection must apply to location, e-mail, phone number, and private messages.

3.24 Error Handling States

As a user, every action must have a loading state.
As a user, every action must have a success state.
As a user, every action must have an error state.
As a user, when I click "Dodaj", something must always happen and a message must be shown.

Page 24 of 51

3.25 Accessibility

As a user, I want appropriate contrast.
As a user, I want visible focus states.
As a user, I want aria-labels.
As a user, I want keyboard operability.
As a user, I want readable error messages.
As a user, I want appropriately sized buttons.

Page 25 of 51

3.26 Quality Gate — "Ready" Definition

The project is considered ready only when:

the application builds,
there are no critical TypeScript errors,
routing works,
Supabase is correctly connected,
Auth works,
RLS is configured,
an account can be created,
a user can log in,
an announcement can be created,
the announcement is saved to the database,
the announcement can be viewed,
the announcement can be deleted,
a message can be sent,
content can be reported,
blocking works,
responsiveness works,
the PWA works,
a basic offline fallback works,
there are no hardcoded secrets.

Page 26 of 51

As a system owner, after implementation the build, TypeScript, lint, routing, forms, auth, RLS, upload, PWA, and mobile layout must all be verified.
As a system owner, work must not stop merely because the code has been written.
As a system owner, the application must pass a real flow covering: entry to the site, registration, login, profile creation, adding an announcement, viewing the announcement, searching, sending a message, replying, reporting content, blocking a user, deleting one's own announcement, and logging out.

3.27 Post-Build Deliverables

As a system owner, after the work the following must be provided: (1) what was built; (2) how to run the project; (3) how to configure Supabase; (4) how to configure ENV; (5) how to run database migrations; (6) how to run the app locally; (7) how to deploy to Vercel; (8) which features are ready; (9) what is prepared for the future; (10) what the limitations are.

Page 27 of 51

3.28 Project ZIP Delivery

As a system owner, I want to deliver the complete finished project as a downloadable ZIP archive, so that the user can download, unzip, configure, and run the whole application locally.
As a system owner, the ZIP must contain the full source of the frontend, the shared backend, the database migrations and DEMO seed data, the PWA assets (manifest, icons, service worker), .env.example, and the documentation described in Section 3.27.
As a system owner, the ZIP must not contain real secrets, .env files with credentials, node_modules, build output, or other generated artifacts.
As a system owner, the archive must be produced from the verified, working build — not from a partially generated or failing state.
As a system owner, the ZIP must be accompanied by a short note stating what is inside, which environment variables must be set, and the order of the run steps.

Page 28 of 51

3.29 Post-Delivery Enhancements („Bajery”)

As a system owner, after the ZIP has been delivered, I want to enhance the site with additional extras („bajery”), so that the product feels more polished and more pleasant to use.
As a resident, I want the extras to make the app feel faster and more alive without adding noise: tasteful motion and transitions, refined card and chip interactions, polished loading/success/error feedback, and a more delightful landing page.
As a resident, I want the extras to remain consistent with the „Sąsiedzka tablica” design concept and the palette in Section 6.1 — no new visual language, no gamification, no likes, no rankings.
As a resident, I want the extras to respect reduced-motion preferences and to keep the app fast on mid-range Android hardware.
As a system owner, the extras must be delivered as an incremental change on top of the delivered ZIP, must keep every accepted flow working, and must pass the quality gate in Section 3.26 again after the enhancement.
As a system owner, the extras must not introduce new data collection, must not expose exact locations, and must not weaken RLS, moderation, or the verified-status rules.

4. User Personas

Page 29 of 51

4.1 Mieszkaniec (Resident)

The primary persona. A person living at the Stare Stawy estate in Oświęcim who wants to handle everyday local needs in one place.

Goals: see what is happening nearby; publish an announcement; ask for help; lend or borrow an item; report a lost/found item; report a local problem or alert; find a local tradesperson; message a neighbour; manage their own profile and content.
Visible information: the board feed, filtered board views, help requests, lendable items, alerts, the professional catalogue, their own conversations, their own profile.
Constraints they care about: their exact address is never shown; the app works even without geolocation; blocking and reporting are available.

4.2 Fachowiec (Local Professional)

A local service provider listed in the catalogue.

Goals: be discoverable in the proper category, present name, description, area of operation, optional phone, optional website, photo/logo; receive enquiries; receive (moderatable) reviews; hold a verified status granted by the system/administrator.
Visible information: their own catalogue listing and its reviews; the verified status that they cannot self-assign.
Distinction from Resident: differs by the existence of a public services listing, verified status, and reviews; not by a separate application.

Page 30 of 51

4.3 Administrator / Moderator

A person operating the admin panel.

Goals: view and act on users (block, delete); view and act on announcements (delete, hide); view and resolve reports; approve alerts; manage professionals; mark profiles as verified.
Visible information: the admin panel views for users, announcements, reports, alerts, and professionals.
Note: the admin panel does not need to be attractive — it must be functional.

4.4 System Actors and External Recipients

Supabase (Auth, PostgreSQL, Storage, RLS) — system actor.
Web Push service — external delivery channel for notifications.

5. Core User Flows

5.1 New User Onboarding

Landing page („STARE STAWY SĄSIEDZI").
„Dołącz" / „Dołącz bezpłatnie".
Registration (e-mail, password).
E-mail confirmation.
Choose name / nickname.
Optional location (or manual „Stare Stawy").
Board of Stare Stawy („Tablica Starych Stawów").

Page 31 of 51

5.2 Returning User

Opens the PWA.
Sees the board.
Sees the newest items.
Adds / replies / writes a message.

5.3 Adding Content

Tap the large „+ Dodaj" button.
Choose: Ogłoszenie / Potrzebuję pomocy / Rzecz do pożyczenia / Alert.
Fill a short form (title, description, category, optional photo).
Set the approximate location.
Publish; see loading → success → error states.

5.4 Help Request Lifecycle

Create a help request.
Set category, urgency, approximate location.
Neighbours respond / contact via messages.
Mark the problem as resolved.

5.5 Item Lending

Owner lists an item with name, description, photo, availability, lending rules, approximate location.
Neighbour browses the lending section.
Neighbour taps „Napisz do właściciela".
Owner and neighbour agree details through 1:1 messages.

Page 32 of 51

5.6 Alert Lifecycle

Resident creates an alert in a category (Droga / utrudnienia, Awaria, Zwierzę, Zguba / znaleziono, Ważne, Inne).
The alert is displayed visually distinguished from ordinary posts.
Administrator approves the alert where approval is required.
Residents report incorrect alerts where needed.

5.7 Finding a Local Professional

Resident opens the local professionals catalogue.
Filters/chooses a category.
Opens a professional profile (name, description, category, area, optional phone/website, photo/logo, verified status, reviews).
Contacts the professional or reads/leaves a review.

5.8 Messaging a Neighbour

Resident opens a conversation or starts one from a profile („Napisz").
Sends a message; sees the date.
Sees read status.
Can block the user or report the conversation.

5.9 Reporting and Blocking

Resident reports an announcement, an alert, a user, or a conversation.
Resident blocks a user.
Administrator views the report and resolves it.
Administrator may delete or hide the content.

Page 33 of 51

5.10 Administrator Moderation Flow

Open admin panel.
View users → block or delete.
View announcements → delete or hide.
View reports → resolve.
Approve alerts.
Manage professionals, including marking profiles as verified.

5.11 Full End-to-End Acceptance Flow

Enter the site.
Register.
Log in.
Create a profile.
Add an announcement.
See the announcement.
Search.
Send a message.
Reply.
Report content.
Block a user.
Delete one's own announcement.
Log out.

Page 34 of 51

5.12 Project Delivery and Enhancement Flow

Verify the working build against the quality gate (Section 3.26).
Package the complete project into a single ZIP archive (source, backend, migrations, DEMO seed, PWA assets, .env.example, documentation), excluding secrets and generated artifacts.
Deliver the ZIP to the user together with the short note describing contents, required environment variables, and run order.
After delivery, plan the post-delivery enhancements („bajery”) within the accepted scope.
Implement the enhancements incrementally on top of the delivered project.
Re-verify the build, the accepted flows, the PWA behaviour, the mobile layout, and the accessibility requirements.
Deliver the enhanced project as an updated archive.

6. Visuals, Colors and Theme

Design character: local + modern + friendly. It must not feel banking, corporate, childish, overly colourful, or like a "start-up from 2020".

Page 35 of 51

6.1 Colour Direction

A restrained, warm, grounded palette that reads as neighbourhood and everyday utility — not finance and not a toy.

Primary — „Sąsiedzka zieleń" (deep, warm green, ~#2F7D5C): trust, community, calm; used for primary actions, active navigation, and key accents.
Surface / Background — „Ciepły piasek" (warm off-white, ~#F7F4EE): the page canvas; softer and friendlier than pure white.
Card surface (~#FFFFFF) on the warm background, with subtle borders and soft shadows.
Text — „Grafit" (~#1E1E1E) for primary text; a mid-grey for secondary text.
Accent — „Ciepły amber" (~#D9822B) for highlights, "Ważne" emphasis, and the urgent affordance.

6.2 Alert Palette (visually distinct from ordinary posts)

-\x20\xf0\x9f\x9a\xa7 Droga / utrudnienia — amber -\x20\xe2\x9a\xa1 Awaria — red -\x20\xf0\x9f\x90\x95 Zwierzę — teal -\x20\xf0\x9f\x94\x91 Zguba / znaleziono — indigo/soft blue -\x20\xe2\x9a\xa0️ Ważne — strong red/amber emphasis -\x20\xf0\x9f\x8c\xb3 Inne — neutral grey

Alert cards must be recognisable at a glance versus regular announcement cards (accent stripe / accent badge / stronger border).

Page 36 of 51

6.3 Typography

One readable sans-serif family with a clean, modern feel; generous sizes.
Clear hierarchy: screen title, section label, card title, body, meta (date, author, location).
High legibility on small phone screens.

6.4 Layout and Spacing

Mobile-first, card-based composition.
Plenty of whitespace; comfortable line lengths.
Large touch targets (buttons comfortably tappable; height at least ~44px).
Category chips for fast filtering.
Bottom navigation on mobile; adaptive layout on tablet and desktop.

6.5 States

Distinct loading, success, and error visuals for every action.
Friendly empty states with an illustrative tone (e.g. „Na razie jest tu spokojnie\x20\xf0\x9f\x91\x80") plus a CTA.

6.6 Dark Mode

Dark mode may be prepared, but it is not more important than the base UX.

Page 37 of 51

7. Signature Design Concept

Concept: „Sąsiedzka tablica" — the neighbourhood board, brought into a warm modern app.

The signature is the feeling of a well-kept local notice board that has been cleaned up and made fast: everything is on one wall, sorted into a handful of clear categories, and anything nearby is close enough to be meaningful.

Design principles that define the experience:

One glance answers the question. The main screen immediately communicates „Co dzieje się teraz na Starych Stawach?" — newest activity first, no search required.
Proximity is the organising metaphor. Location is expressed relationally („~300 m od Ciebie", „Stare Stawy", „okolice ul. X"), never as an exact address. The product is about closeness, not addresses.
Few, meaningful categories. Ten announcement categories, six alert categories, and a small professional category set. Ordered, not endless.
Cards as pin-ups. Announcements, help requests, lendable items, and alerts appear as distinct, scannable cards; alerts carry a differentiated visual treatment so they stand apart instantly.
Local voice. Copy speaks as a neighbour: „u nas", „sąsiedzi", „Twoja okolica", „na Starych Stawach" — warm but restrained, without over-repeating the estate name.
Quiet, not gamified. No likes, no rankings, no badges for engagement. Utility is the reward.
Feels installed, not visited. On a phone the app behaves and looks like a mobile application, not a shrunken website.

Page 38 of 51

8. Interaction Model & Motion Direction

8.1 Interaction Model

Mobile-first interaction. Thumb-reachable primary actions; the large „+ Dodaj" button is the central creation affordance.
Bottom navigation with five destinations:\x20\xf0\x9f\x8f\xa0 Tablica,\x20\xf0\x9f\xa4\x9d Pomoc,\x20\xf0\x9f\x94\xa7 Pożycz,\x20\xf0\x9f\x92\xac Wiadomości,\x20\xf0\x9f\x91\xa4 Profil.
Chips for filtering on the board:\x20\xf0\x9f\x93\xa2 Wszystko,\x20\xf0\x9f\xa4\x9d Pomoc,\x20\xf0\x9f\x94\xa7 Pożycz,\x20\xf0\x9f\x8e\x81 Oddam,\x20\xf0\x9f\x9a\xa8 Ważne.
Progressive disclosure on creation. Instead of one long form, the user first picks what to add (Ogłoszenie / Potrzebuję pomocy / Rzecz do pożyczenia / Alert), then completes a short form.
Direct-contact lending. No booking flow — the lending interaction resolves to „Napisz do właściciela" and then messages.
Explicit feedback everywhere. Every action produces a visible loading, success, or error state; a tap never results in nothing happening.
Safety actions in reach. Report and block are available from posts, profiles, and conversations.
Accessible by default. Keyboard reachable, visible focus states, aria-labels, readable error messages, adequately sized controls.

Page 39 of 51

8.2 Motion Direction

Subtle animations only — gentle transitions between screens, soft card entry, tasteful feedback on taps and state changes.
Purposeful, not decorative. Motion clarifies state changes (published, sent, resolved, blocked) rather than entertaining.
Fast. Motion must never make the app feel slow; responsiveness on mid-range Android hardware is the benchmark.
Reduced-motion friendly. Users who prefer reduced motion should receive a calm, largely static experience.

9. Non-Functional Requirements

9.1 Usability

A resident must see immediately what is happening in their area on opening the app.
Forms must be short; the user must not be forced through lengthy inputs.
All empty screens must present a meaningful message and a CTA.

9.2 Performance

The app must feel fast on mobile devices.
Basic caching via a service worker, plus a basic offline fallback.

Page 40 of 51

9.3 Responsiveness (Priority Order)

Android mobile
iPhone mobile
Tablet
Desktop

On a phone the application must work perfectly.

9.4 Security

Reporting of announcements, alerts, users, and conversations.
Blocking of users.
Moderation, content deletion, and moderation statuses.
Rate limiting.
Spam protection.
Basic bot protection.
Data validation.
Row Level Security enforced at the database level; the system must not trust frontend-only protections.
Secured uploads (size limits, MIME validation, safe file names, ownership restrictions).
The „ZWERYFIKOWANY" status must never be user-settable.
No automatic labelling of a business as „oszust".

Page 41 of 51

9.5 Privacy

Never publicly display exact coordinates, exact addresses, full names, or phone numbers of residents by default.
Special protection for location, e-mail, phone number, and private messages.
Data minimisation: do not collect data the application does not need.
Account deletion, own-content deletion, and logout must be possible.
Separate pages for privacy policy, terms, and contact, plus basic data-processing information.

9.6 Location Handling

Location sharing is optional and browser-based.
Safe rounding/masking must be implemented so exact locations cannot be reconstructed.
Absence of location must never block use of the app.
Manual fallback: „Stare Stawy".
Display forms: „~300 m od Ciebie", „Stare Stawy", „okolice ul. X".

9.7 Accessibility

Adequate contrast, visible focus states, aria-labels, keyboard operability, readable error messages, appropriately sized buttons and targets.

Page 42 of 51

9.8 SEO (despite being a PWA)

Title and description.
Open Graph.
Twitter/X card.
Favicon.
robots.
sitemap, if the architecture permits.
The landing page must explain „Stare Stawy — Sąsiedzi" and „Lokalna społeczność mieszkańców Starych Stawów w Oświęcimiu."

9.9 PWA Requirements

Manifest, icons, theme color, install prompt, service worker, basic caching, responsiveness, mobile operation, and the ability to add the app to the Android home screen.

9.10 Localisation

All application interface copy in Polish.
Locality tone consistent with the „To jest nasze osiedle" principle.

9.11 Code Quality

Modular, readable, typed, easy to extend.
No unnecessary over-engineering.
Do not install 50 libraries if something can be done natively.

9.12 Configuration and Secrets

Provide .env.example with a description of the required variables.
Never embed real API keys in code.

Page 43 of 51

9.13 Testability

Build, TypeScript, lint, routing, forms, auth, RLS, upload, PWA, and mobile layout must be verifiable.
The documented end-to-end flow (Section 5.11) must pass.

Page 44 of 51

10. Tech Stack

The following stack is preferred and may be substituted only if the repository already defines a technology:

Framework: Next.js
Language: TypeScript
Styling: Tailwind CSS
UI components: shadcn/ui
Backend / Platform: Supabase
- Supabase Auth
- PostgreSQL
- Storage
- Row Level Security
PWA layer: web manifest, icons, theme color, install prompt, service worker, basic caching, offline fallback
Deployment target: Vercel
Configuration: .env.example documenting required variables, including:
- NEXT_PUBLIC_SUPABASE_URL=
- NEXT_PUBLIC_SUPABASE_ANON_KEY=
(or the equivalent current variables required by the chosen architecture)
Notifications: architecture prepared for Web Push, with complete implementation and clearly documented ENV/config where additional configuration is required.

Page 45 of 51

10.1 Database Schema (Indicative)

Example tables: profiles, posts, post_categories, comments, messages, conversations, help_requests, borrow_items, alerts, professionals, professional_reviews, reports, blocks, notifications.

Each table must have sensible id, created_at, updated_at, and — where needed — user_id, status, deleted_at. RLS must be enabled. No tables should be created without need.

10.2 Provisioned Services and Runtime Topology

The provisioned service inventory (Section 2.8) is authoritative for the runtime:

frontend — React application UI, built and served as the PWA shell; all pages, forms, and client-side state live here.
backend — one shared FastAPI process exposing the application APIs and domain modules. Feature APIs (board, help, lending, alerts, professionals, messaging, notifications, reports/moderation, admin, uploads) are added as routes and modules inside this process; no additional containers or ingress routes are introduced for them.
database — MariaDB holding application-owned persistent data, accessed only by the backend.

Supabase Auth, Supabase Storage, and the Web Push service remain external system actors configured through documented environment variables. Where the architecture requires a background job (for example delivering Web Push notifications), it runs as a worker process alongside the shared backend and is documented as such.

Page 46 of 51

10.3 Delivery Packaging

The complete project is packaged as a single downloadable ZIP archive produced from the verified build.
The archive contains the frontend, the shared backend, database migrations and DEMO seed data, PWA assets, .env.example, and the documentation from Section 3.27.
The archive excludes real secrets, .env files with credentials, node_modules, build output, and other generated artifacts.

11. Assumptions and Constraints

11.1 Scope Constraints (MVP)

No group chat in the MVP.
No complex item reservation system — contacting the owner is sufficient.
No payments: Stripe must not be integrated at this stage unless the architecture requires a placeholder.
Monetisation (business profiles, highlights, local ads, sponsored posts) is future-only.
The admin panel must be functional, not necessarily attractive.

Page 47 of 51

11.2 Product Constraints

The product is strictly for Stare Stawy in Oświęcim; it is not a general Polish residents' portal.
The product must not copy Facebook, and it must not become "another Facebook".
No gamification, artificial likes, or meaningless rankings.
No 30-category taxonomy.
No feed stuffed with unnecessary features.
No complicated member panel.
The architecture must not depend heavily on the working project name.

11.3 Privacy Constraints

Never publish residents' full name, exact address, exact coordinates, or phone number by default.
Never publicly display exact coordinates.
Never collect data the app does not need.

11.4 Quality Constraints

No mockups, no prototype with dummies, no screens only, and no TODOs left in key functions.
The result must be a working application that can be run and deployed after environment configuration.
No hardcoded secrets.
Each function must answer a real problem of a Stare Stawy resident.

Page 48 of 51

11.5 Decision-Making Assumptions

Where the specification is silent (e.g. button colour, table naming), reasonable design decisions are to be made and implemented rather than blocking progress.
A question may be asked only if a decision is significant and affects the architecture.

11.6 Environment and Tooling Assumptions

Supabase is the backend platform; environment configuration is performed via .env.
Database migrations must be runnable and documented.
Deployment target is Vercel.
Development environment includes seed/demo data, clearly marked as DEMO, with no impersonation of real residents and no fabricated "real" reviews.

11.7 Out-of-Scope for the First Version

Group chat.
Complex borrowing reservation workflow.
Payments and paid tiers.
Broad geographic coverage beyond the Stare Stawy estate.

Page 49 of 51

11.8 Delivery and Enhancement Constraints

The complete finished project must be delivered as a single downloadable ZIP archive before any enhancement work begins.
The ZIP must be produced from the verified working build and must not contain secrets or generated artifacts.
Post-delivery enhancements („bajery”) are additive only: they must not remove or weaken accepted requirements, must not add gamification, likes, rankings, group chat, reservations, or payments, and must not introduce new data collection or expose exact locations.
Enhancements must preserve the „Sąsiedzka tablica” design concept, the palette in Section 6.1, reduced-motion support, and mobile performance.
After the enhancements, the quality gate in Section 3.26 must pass again.

Page 50 of 51

12. Glossary

Term	Definition
Stare Stawy	The housing estate in Oświęcim for which the application is built.
„Stare Stawy — Sąsiedzi"	Working project name; may change and must not drive architecture.
Tablica Sąsiadów	The main board feed of the application, where residents publish announcements.
Ogłoszenie	An announcement published on the board, with title, description, category, optional photo, date, author, approximate location, status, reply count, and report option.
Pomoc Lokalna	The separate module for help requests, with category, urgency, approximate location, and resolved status.
Pożyczalnia Rzeczy	The module where residents list items they are willing to lend (drill, ladder, washing vacuum, tools, trailer, garden equipment), each with name, description, photo, owner, approximate location, availability, and lending rules.
Alert Osiedlowy	A neighbourhood alert in a separate section, visually distinguished from ordinary announcements; categories: Droga / utrudnienia, Awaria, Zwierzę, Zguba / znaleziono, Ważne, Inne.
Fachowiec	A local professional listed in the services catalogue with name, description, category, area of operation, optional phone, optional website, photo/logo, verified status, and reviews.
ZWERYFIKOWANY (Verified)	A system/administrator-controlled status on a professional profile; users may never set it themselves.
Wiadomości	The in-app 1:1 messaging module: conversation, conversation list, messages with date, read status, blocking, and conversation reporting. Group chat is out of MVP.
Powiadomienia	Notifications for new messages, replies to announcements, important alerts, and activity on the user's own content.
DEMO data	Seed/demo entries in the development environment, explicitly marked as DEMO; never impersonating real residents and never fabricating real reviews.
Masked location	The relational, safe representation of position („~300 m od Ciebie", „Stare Stawy", „okolice ul. X") that never exposes exact coordinates or addresses.
RLS	Row Level Security — database-level access control enforced in Supabase, not solely in the frontend.
PWA	Progressive Web App — installable, manifest-driven, service-worker-cached web application that behaves like a mobile app.
MVP	Minimum Viable Product — the first released scope defined in Section 3.
ZIP delivery	The single downloadable archive containing the complete finished project (source, backend, migrations, DEMO seed, PWA assets, `.env.example`, documentation), excluding secrets and generated artifacts.
Bajery (extras)	The post-delivery, additive enhancements that polish the site within the accepted scope, without gamification, likes, rankings, or new data collection.

Page 51 of 51

deep-polecenie

Comments (0)