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

> Architecture diagram of the GitHub repository asef69/core-buetian--your-buetian-social-media-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asef69/core-buetian--your-buetian-social-media-app
- Repository: https://github.com/asef69/core-buetian--your-buetian-social-media-app

## Overview

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.

Main entry points: [`BACKEND/core_buetians/urls.py`](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/urls.py) (API router), [`BACKEND/sql/DB_SCHEMA.sql`](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/sql/DB_SCHEMA.sql) (SQL layer), [`BACKEND/utils/authentication.py`](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/utils/authentication.py) (Shared utils), [`FRONTEND/src/main.jsx`](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/main.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_manage["manage.py<br/>django entrypoint<br/>[manage.py]"]
  node_core_settings["Core settings<br/>django core<br/>[settings.py]"]
  node_core_urls["API router<br/>django routing<br/>[urls.py]"]
  node_core_asgi["ASGI app<br/>channels entrypoint<br/>[asgi.py]"]
  node_users_app["Users<br/>auth domain<br/>[views.py]"]
  node_posts_app["Posts<br/>content domain<br/>[views.py]"]
  node_chat_app["Chat<br/>realtime domain<br/>[consumers.py]"]
  node_groups_app["Groups<br/>community domain<br/>[views.py]"]
  node_forums_app["Forums<br/>discussion domain<br/>[views.py]"]
  node_market_app["Marketplace<br/>commerce domain<br/>[views.py]"]
  node_notif_app["Notifications<br/>event domain<br/>[views.py]"]
  node_utils_shared["Shared utils<br/>backend support<br/>[authentication.py]"]
  node_chat_websocket["Chat routing<br/>channels routing<br/>[routing.py]"]
  node_run_fullstack["Launcher<br/>dev runner<br/>[run_fullstack.py]"]
end

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>react entry<br/>[main.jsx]"]
  node_auth_context["Auth context<br/>client state<br/>[AuthContext.jsx]"]
  node_api_service["API service<br/>client api<br/>[apiService.js]"]
  node_pages["Pages<br/>ui routes<br/>[Home.jsx]"]
  node_shared_ui["Shared UI<br/>ui components<br/>[Navbar.jsx]"]
  node_client_styles["Styles<br/>client styling<br/>[index.css]"]
end

subgraph group_data["Data"]
  node_sql_schema[("SQL layer<br/>postgres logic<br/>[DB_SCHEMA.sql]")]
end

node_manage -->|"loads"| node_core_settings
node_core_settings -->|"wires"| node_core_urls
node_core_settings -->|"configures"| node_core_asgi
node_core_urls -->|"routes"| node_users_app
node_core_urls -->|"routes"| node_posts_app
node_core_urls -->|"routes"| node_chat_app
node_core_urls -->|"routes"| node_groups_app
node_core_urls -->|"routes"| node_forums_app
node_core_urls -->|"routes"| node_market_app
node_core_urls -->|"routes"| node_notif_app
node_chat_app -->|"uses"| node_chat_websocket
node_users_app -->|"uses"| node_utils_shared
node_posts_app -->|"uses"| node_utils_shared
node_groups_app -->|"uses"| node_utils_shared
node_forums_app -->|"uses"| node_utils_shared
node_market_app -->|"uses"| node_utils_shared
node_notif_app -->|"uses"| node_utils_shared
node_chat_app -->|"persists"| node_sql_schema
node_users_app -->|"reads/writes"| node_sql_schema
node_posts_app -->|"reads/writes"| node_sql_schema
node_groups_app -->|"reads/writes"| node_sql_schema
node_forums_app -->|"reads/writes"| node_sql_schema
node_market_app -->|"reads/writes"| node_sql_schema
node_notif_app -->|"derives"| node_sql_schema
node_run_fullstack -->|"starts"| node_core_settings
node_run_fullstack -->|"starts"| node_app_shell
node_app_shell -->|"uses"| node_auth_context
node_app_shell -->|"uses"| node_api_service
node_app_shell -->|"renders"| node_pages
node_pages -->|"composes"| node_shared_ui
node_pages -->|"styles"| node_client_styles
node_pages -->|"fetches"| node_api_service
node_shared_ui -->|"consumes"| node_auth_context

click node_manage "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/manage.py"
click node_core_settings "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/settings.py"
click node_core_urls "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/urls.py"
click node_core_asgi "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/asgi.py"
click node_users_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/users/views.py"
click node_posts_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/posts/views.py"
click node_chat_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/chat/consumers.py"
click node_groups_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/groups/views.py"
click node_forums_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/forums/views.py"
click node_market_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/marketplace/views.py"
click node_notif_app "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/notification/views.py"
click node_utils_shared "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/utils/authentication.py"
click node_chat_websocket "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/chat/routing.py"
click node_sql_schema "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/sql/DB_SCHEMA.sql"
click node_run_fullstack "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/run_fullstack.py"
click node_app_shell "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/main.jsx"
click node_auth_context "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/context/AuthContext.jsx"
click node_api_service "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/services/apiService.js"
click node_pages "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/pages/Home/Home.jsx"
click node_shared_ui "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/components/Navbar.jsx"
click node_client_styles "https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/styles/index.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manage,node_core_settings,node_core_urls,node_core_asgi,node_users_app,node_posts_app,node_chat_app,node_groups_app,node_forums_app,node_market_app,node_notif_app,node_utils_shared,node_chat_websocket,node_run_fullstack toneBlue
class node_app_shell,node_auth_context,node_api_service,node_pages,node_shared_ui,node_client_styles toneAmber
class node_sql_schema toneMint
```

## Components

### Backend

Django API, domain apps, Channels, and shared backend utilities

- [manage.py](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/manage.py): django entrypoint · Administrative command entrypoint for the Django backend · `BACKEND/manage.py`
- [Core settings](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/settings.py): django core · Global Django configuration and request wiring · `BACKEND/core_buetians/settings.py`
- [API router](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/urls.py): django routing · Main HTTP URL dispatcher that mounts domain API surfaces · `BACKEND/core_buetians/urls.py`
- [ASGI app](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/core_buetians/asgi.py): channels entrypoint · ASGI configuration for HTTP and WebSocket handling · `BACKEND/core_buetians/asgi.py`
- [Users](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/users/views.py): auth domain · Accounts, profiles, authentication, and user-facing profile actions · `BACKEND/users/views.py`
- [Posts](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/posts/views.py): content domain · Post creation, reading, and interaction workflows · `BACKEND/posts/views.py`
- [Chat](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/chat/consumers.py): realtime domain · WebSocket chat, message delivery, and persisted conversation data · `BACKEND/chat/consumers.py`
- [Groups](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/groups/views.py): community domain · Group membership, pages, and group interaction endpoints · `BACKEND/groups/views.py`
- [Forums](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/forums/views.py): discussion domain · Forum threads and discussion-oriented endpoints · `BACKEND/forums/views.py`
- [Marketplace](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/marketplace/views.py): commerce domain · Product listings and marketplace interactions · `BACKEND/marketplace/views.py`
- [Notifications](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/notification/views.py): event domain · Cross-cutting notification generation and delivery endpoints · `BACKEND/notification/views.py`
- [Shared utils](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/utils/authentication.py): backend support · Authentication, permissions, pagination, database, uploads, and exceptions · `BACKEND/utils/authentication.py`
- [Chat routing](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/chat/routing.py): channels routing · WebSocket route mapping for the chat subsystem · `BACKEND/chat/routing.py`
- [Launcher](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/run_fullstack.py): dev runner · Convenience launcher for running frontend and backend together · `run_fullstack.py`

### Frontend

React UI, pages, shared state, and client-side services

- [App shell](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/main.jsx): react entry · Client bootstrap and top-level application wiring · `FRONTEND/src/main.jsx`
- [Auth context](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/context/AuthContext.jsx): client state · Centralized authentication state and session flow on the client · `FRONTEND/src/context/AuthContext.jsx`
- [API service](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/services/apiService.js): client api · HTTP data access layer used by pages and hooks · `FRONTEND/src/services/apiService.js`
- [Pages](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/pages/Home/Home.jsx): ui routes · Route-level screens for posts, groups, marketplace, forums, profile, search, and chat · `FRONTEND/src/pages/Home/Home.jsx`
- [Shared UI](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/components/Navbar.jsx): ui components · Reusable components, route guards, loaders, and shared interaction widgets · `FRONTEND/src/components/Navbar.jsx`
- [Styles](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/FRONTEND/src/styles/index.css): client styling · App-wide and feature-specific CSS for the frontend · `FRONTEND/src/styles/index.css`

### Data

PostgreSQL schema, functions, views, triggers, and procedures

- [SQL layer](https://github.com/asef69/core-buetian--your-buetian-social-media-app/blob/main/BACKEND/sql/DB_SCHEMA.sql): postgres logic · Schema, indexes, views, functions, procedures, and triggers that hold business logic · `BACKEND/sql/DB_SCHEMA.sql`

## Connections

- manage.py → Core settings: loads · Django management commands use shared project settings
- Core settings → API router: wires · Project settings connect the main URL configuration
- Core settings → ASGI app: configures · Settings support the ASGI runtime used by HTTP and WebSockets
- API router → Users: routes · Main API router mounts the user domain
- API router → Posts: routes · Main API router mounts the posts domain
- API router → Chat: routes · Main API router mounts chat endpoints
- API router → Groups: routes · Main API router mounts group endpoints
- API router → Forums: routes · Main API router mounts forum endpoints
- API router → Marketplace: routes · Main API router mounts marketplace endpoints
- API router → Notifications: routes · Main API router mounts notification endpoints
- Chat → Chat routing: uses · Chat domain exposes live WebSocket routing
- Users → Shared utils: uses · Domain apps rely on shared auth and permission helpers
- Posts → Shared utils: uses · Shared utilities support validation, pagination, and uploads
- Groups → Shared utils: uses · Group workflows reuse common backend support
- Forums → Shared utils: uses · Forum endpoints use shared backend helpers
- Marketplace → Shared utils: uses · Marketplace endpoints reuse common backend support
- Notifications → Shared utils: uses · Notification logic depends on shared infrastructure helpers
- Chat → SQL layer: persists · Chat data and derived behavior are backed by PostgreSQL logic
- Users → SQL layer: reads/writes · User data is stored in PostgreSQL and may use SQL-side logic
- Posts → SQL layer: reads/writes · Post workflows depend on database tables, views, and functions
- Groups → SQL layer: reads/writes · Group workflows depend on database-side logic and storage
- Forums → SQL layer: reads/writes · Forum workflows depend on database-side logic and storage
- Marketplace → SQL layer: reads/writes · Marketplace workflows depend on database-side logic and storage
- Notifications → SQL layer: derives · Notifications are often produced from database-backed domain events
- Launcher → Core settings: starts · Launcher brings up the Django backend during local development
- Launcher → App shell: starts · Launcher brings up the Vite frontend during local development
- App shell → Auth context: uses · App bootstrap installs shared authentication state
- App shell → API service: uses · Client app talks to backend through a central API layer
- App shell → Pages: renders · React app is composed around route-level pages
- Pages → Shared UI: composes · Screens are built from shared navigation and reusable components
- Pages → Styles: styles · Pages are themed through shared CSS assets
- Pages → API service: fetches · Route-level screens load data through the service layer
- Shared UI → Auth context: consumes · Protected and authenticated UI depends on shared auth state