asef69/core-buetian--your-buetian-social-media-app

1. System shape

Core BUETians is a split frontend/backend platform: a React 18 + Vite client talks to a Django 4.2 backend built with Django REST Framework, while real-time chat uses Django Channels over WebSockets. PostgreSQL is the primary datastore, and the backend is organized around feature domains rather than a single monolith.

2. Backend boundary and entrypoints

The backend root lives in core_buetians/, which contains global settings plus the main HTTP/ASGI/WSGI wiring. core_buetians/urls.py and the domain URL modules define the API surface, while asgi.py enables both normal HTTP traffic and the WebSocket path used by chat. manage.py is the standard Django control entrypoint.

3. Domain-oriented Django apps

Each major business area is isolated into its own app: users, posts, chat, groups, forums, marketplace, and notification. This is the main architectural boundary in the backend. The apps carry their own models, views, serializers, URLs, tests, and in some cases extended_views or auth_views for specialized endpoints.

4. Data flow for REST APIs

Most user actions follow a simple path: the React app calls a domain API endpoint, the Django view/serializer layer validates the request, and the app reads or writes PostgreSQL. The backend returns JSON, and the frontend renders it through route-level pages such as Posts, Groups, Marketplace, Forums, Profile, and Search.

5. Real-time chat path

Chat is the only clearly real-time subsystem. The frontend chat page connects to a WebSocket endpoint handled by chat/consumers.py and chat/routing.py, with Channels managing live message delivery. Chat messages are also persisted, so the system has both a transient real-time transport and durable storage/query behavior.

6. Notification orchestration

Notifications are treated as a cross-cutting domain rather than a UI-only concern. Multiple backend actions can create them: likes, comments, follows, messages, group activity, and other interactions. This makes notifications a downstream effect of other domains instead of an isolated user-triggered feature.

7. Shared backend utilities

Common infrastructure lives in utils/: authentication, permissions, pagination, database helpers, file upload handling, exception types, and media config. These utilities form the shared service layer used across apps, keeping repeated concerns out of the domain modules.

8. Database is more than tables

The sql/ directory is a major architectural asset. It contains schema, indexes, views, functions, procedures, and triggers, which means a fair amount of business logic is pushed into PostgreSQL. That affects the architecture materially: the app layer is not the only place where counters, notifications, derived fields, and transactional workflows are maintained.

9. Frontend structure

The frontend is organized by pages and reusable components, with shared state in context/, API access in services/, reusable logic in hooks/, and app-wide styling in styles/. The UI is composed around domain pages that mirror the backend areas, which keeps the frontend aligned with the API boundaries.

10. Cross-cutting UX and platform concerns

Authentication flows are centralized in the frontend AuthContext and backend user/auth views, while protected routes enforce access on the client. Media uploads are supported through the backend media structure and upload utilities. Error handling, online status, skeleton loaders, and toasts are treated as shared UX infrastructure rather than feature-specific code.

11. Search and content discovery

Search is surfaced as its own route set under core_buetians/search_*, which suggests a cross-domain discovery layer rather than a single app-local search. This is important for diagramming because it sits above multiple domains like users, posts, groups, forums, and marketplace content.

12. Local runtime and deployment boundary

Development runs as two processes: a Django backend on port 8000 and a Vite frontend on port 3000, with run_fullstack.py acting as a convenience launcher. The repository also includes Swagger/ReDoc exposure, indicating the backend is intended to be inspected and integrated as an API-first service.