Κανόνες απλότητας

Το Bubllio χρησιμοποιεί Django REST Framework στο backend και React, TanStack Router, TanStack Query, Axios, Zustand, Material UI, React Hook Form και Zod στο frontend. Τα εργαλεία αυτά καλύπτουν τις σημερινές ανάγκες του project. Νέες abstractions προστίθενται όταν απλοποιούν ένα υπάρχον pattern, όχι απλώς για να εισαγάγουν ακόμη ένα επίπεδο.

Ακολουθήστε τη συντομότερη χρήσιμη διαδρομήΑντιγραφή συνδέσμου ενότητας

Για ένα συνηθισμένο read ή write, κρατήστε τη διαδρομή σύντομη:

route → view → serializer → model
page → feature hook → feature service → api client

Προσθέστε service όταν η επιχειρησιακή λογική επαναχρησιμοποιείται, χρειάζεται transaction, επικοινωνεί με εξωτερικό σύστημα ή είναι δύσκολο να δοκιμαστεί μέσα σε view. Παραδείγματα: αποδοχή invitation, SMTP delivery, μεταβίβαση ownership και εκτέλεση Automation. Μην προσθέτετε service που καλεί μία μέθοδο model μόνο μία φορά.

Προσθέστε shared component αφού η ίδια συμπεριφορά UI εμφανιστεί σε τουλάχιστον δύο features. Κρατήστε τα feature-specific components μέσα στο αντίστοιχο feature. Αποφύγετε γενικά components με configuration props για υποθετικές μελλοντικές οθόνες.

Κάθε ευθύνη έχει έναν ιδιοκτήτηΑντιγραφή συνδέσμου ενότητας

• Django models και database constraints διατηρούν μόνιμα invariants.
• Serializers επικυρώνουν API input και output.
• Views συντονίζουν HTTP και επιλέγουν το απαιτούμενο tenant capability.
• Services περιέχουν επαναχρησιμοποιήσιμη επιχειρησιακή λογική και εξωτερικές παρενέργειες.
• React pages συνθέτουν την οθόνη· δεν καλούν Axios και δεν κατασκευάζουν API URLs.
• Feature hooks διαχειρίζονται TanStack Query keys, fetching, mutations και invalidation.
• Zustand διατηρεί μόνο το client session και περιορισμένο client state που μοιράζονται οθόνες.
• Το UserProfile αποθηκεύει προσωπικά onboarding data· το OrganizationMembership αποθηκεύει workspace role data. Μην τοποθετείτε προσωπικά πεδία σε membership records.
• Τα Material UI theme files περιέχουν τα visual tokens και τα κοινά component defaults.

Όταν ένας κανόνας χρειάζεται και στα δύο επίπεδα, η υλοποίηση του backend είναι η έγκυρη. Το frontend validation βελτιώνει το feedback, αλλά δεν αντικαθιστά το validation του serializer.

Το tenant context πρέπει να είναι πάντα σαφέςΑντιγραφή συνδέσμου ενότητας

Κάθε backend operation που ανήκει σε Organization πρέπει να εντοπίζει το Organization από το URL και να ελέγχει το membership του authenticated χρήστη. Κάθε frontend Organization URL και TanStack Query key πρέπει να περιλαμβάνει το Organization ID. Μην εμπιστεύεστε organization field από request body για να αποφασίσετε ownership.

Ονομάστε συγκεκριμένα τα πράγματαΑντιγραφή συνδέσμου ενότητας

Προτιμήστε ονόματα όπως useWorkspaceMembers, OrganizationInvitation και organizationService.createEmailAccount αντί για useResource, DomainGateway ή CrudManager. Ο contributor πρέπει να καταλαβαίνει από το όνομα και τη διαδρομή σε ποιο feature ανήκει ο κώδικας.

Μια αλλαγή πρέπει να επαληθεύεται εύκολαΑντιγραφή συνδέσμου ενότητας

Κάθε νέο endpoint χρειάζεται στοχευμένα API tests για επιτυχία, validation, authorization και tenant isolation. Κάθε νέα user flow χρειάζεται στοχευμένο browser test. Χρησιμοποιήστε τα υπάρχοντα commands:

# frontend/
npm run format:check
npm run lint
npm test
npm run build
npm run test:e2e

# repository root
uv run python src/manage.py check
uv run python src/manage.py makemigrations --check --dry-run
uv run python src/manage.py test bubllio_crm organizations access onboarding companies contacts automations

Αν κάποιος contributor δεν μπορεί να εξηγήσει ένα module σε σύντομη παράγραφο, χωρίστε το με βάση τις ευθύνες του πριν προσθέσετε άλλη συμπεριφορά.