Documentația Taraba

Taraba este o piață online românească pentru produse noi și second hand, cu plată protejată, livrare prin curier și moderare făcută de oameni. Platforma are trei aplicații: site-ul public (cumpărători și vânzători), Backoffice (echipa de operațiuni) și CRM (marketing), servite de un singur API.

Cuprins

Business

Document	Pentru cine	Ce găsești
Modelul de business	management, investitori, echipă	problema, propunerea de valoare, segmente, venituri, economia unei tranzacții, costuri, riscuri, indicatori
Procesele de business	operațiuni, management, analiști	15 procese cu diagrame BPMN, reguli, excepții, indicatori și complexitate
Roluri și responsabilități	management, echipă	rolurile echipei, permisiunile și cine ce face în fiecare proces
Diagrame de analiză	toată lumea	contextul sistemului, cazurile de utilizare, fluxurile de date (DFD), ERD-ul conceptual și diagramele de activitate, cu ghidul de citire

Utilizare

Document	Pentru cine
Site-ul public	cumpărători, vânzători, suport (pentru a explica clienților)
Backoffice	moderatori, suport, financiar, administratori
CRM	marketing

Tehnic

Document	Ce găsești
Arhitectura	componente, module, comunicare, procese periodice, decizii de arhitectură
Specificații tehnice	tehnologii și versiuni, cerințe nefuncționale măsurate, limite, configurare
Modelul de date	toate cele 40 de entități, coloane, relații, indecși, diagrame ER (generat)
Fluxuri tehnice	stările anunțului și comenzii, secvențe, bani, notificări
Referința API	toate operațiile GraphQL, accesul și erorile (generat)
Securitate și protecția datelor	autentificare, permisiuni, date personale, GDPR, fișiere
Testare	tipuri de teste, cum se rulează, praguri de calitate
Instalare	instalare pas cu pas (Docker și dezvoltare locală)
Operare	configurare, copii de siguranță, monitorizare, incidente
Release	pașii unei versiuni noi, verificări, revenire

Referințe detaliate pe module (în engleză, scrise în timpul dezvoltării): AUTH, CATALOG, ORDERS, NOTIFICATIONS, CRM, WORKSPACE, SITE, DATABASE, TESTING, ROADMAP.

Site-ul documentației

Aceeași documentație e disponibilă ca site intern, cu căutare, meniu și temă luminoasă/întunecată, generat din aceste fișiere Markdown (sursa rămâne Markdown-ul):

Cum	Comandă	Adresă
Docker (cu restul platformei)	docker compose up -d --build docs	http://localhost:8083
Dezvoltare (se reîncarcă la fiecare modificare)	pnpm docs:dev	http://localhost:5176
Doar build-ul static	pnpm docs:build	apps/docs/dist

Containerul e publicat doar pe 127.0.0.1 (documentație internă); pentru acces din rețea, pune-l în spatele VPN-ului sau al autentificării companiei.

Toate adresele proiectului (aplicații, API, servicii, porturi, conturi demo), pe medii: URLS.md.

Diagramele

Toate diagramele se deschid cu un clic într-o fereastră cu zoom, ecran complet, redare pas cu pas și descărcare în SVG, PNG, JPG sau GIF animat. Tipuri: context (C4), cazuri de utilizare, activitate și secvență (UML), BPMN, fluxuri de date (Gane–Sarson), ERD conceptual și tehnic, stări, arhitectură. Diagramele se deschid și se citesc după ghidul din Diagrame de analiză.

Cum se actualizează documentația

Părțile marcate generat și toate diagramele se produc din cod, ca să nu rămână în urma lui:

pnpm docs:generate

Comanda exportă schema GraphQL și metadatele entităților (docs/generated/), apoi rulează docs/tools/build_docs.py, care scrie modelul de date, referința API și toate imaginile SVG din docs/imagini/. Apoi pnpm docs:build reface site-ul. Procesele de business se definesc în docs/tools/process_defs.py (diagramă și text din aceeași definiție). Textele scrise de mână (acest fișier, ghidurile de utilizare, modelul de business) se actualizează odată cu funcționalitatea, în același pull request.