# neoastra303/socialmedia-app architecture

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

- Interactive diagram: https://gitdiagram.com/neoastra303/socialmedia-app
- Repository: https://github.com/neoastra303/socialmedia-app

## Overview

1. **Overall shape**
This is a monolithic Django 5.1 application organized into feature apps rather than separate services. The main runtime is Django served over ASGI, with Daphne/Channels handling both normal HTTP traffic and WebSocket traffic.

2. **Request entry points**
`socialmediaproject/urls.py` is the main HTTP router, while `socialmediaproject/routing.py` wires WebSocket routes for chat and notifications. `asgi.py` is the async entrypoint; `wsgi.py` exists for traditional deployment, but the presence of Channels makes ASGI the important boundary.

3. **Core domain apps**
The business logic is split across `posts`, `users`, `direct_messages`, `notifications`, `reports`, and two search-related apps: `search` and `searchapp`. Each app owns its own models, views, forms, URLs, tests, and in several cases migrations, which makes the architecture modular but still tightly coupled through shared Django models and auth.

4. **User and identity subsystem**
`users` is the identity hub: registration, email-based authentication, profiles, privacy, blocking, follow requests, and settings live here. It also contains a custom authentication backend (`users/backends/email_auth.py`), signals, and background tasks, so this app is not just UI—it governs login behavior and account lifecycle.

5. **Content subsystem**
`posts` is the largest domain area and appears to own feeds, post CRUD, comments, reactions, bookmarks, hashtags, stories, and media upload handling. It also includes a DRF serializer layer, a custom template tag for linkifying content, and a management command (`cleanup_stories`) for expiring time-limited story records.

6. **Messaging and notifications**
`direct_messages` and `notifications` are the real-time interaction layer. Both have WebSocket consumers, which means server events can be pushed instantly to connected clients; notifications also have a classic database-backed list view/template for persisted notifications.

7. **Moderation and safety**
`reports` handles abuse/content reporting and moderation workflows. Cross-cutting safety concerns are reinforced by middleware for exception handling and rate limiting, plus a shared file validation utility in `utils/file_validation.py` for upload constraints.

8. **Search**
The search functionality is split into a backend-facing `search` app and a UI-facing `searchapp` app with templates for advanced search and results pages. This suggests search logic and presentation are deliberately separated, even though they are still within the same Django project.

9. **Presentation layer**
Server-rendered templates are the main UI mechanism. Shared layout lives in `templates/base.html`, while app-specific templates exist for posts, users, messages, notifications, reports, and search. Static assets are simple CSS/JS files, with built outputs mirrored under `staticfiles/` for deployment.

10. **Data and persistence**
The system relies on Django ORM models and migrations in each app, with PostgreSQL as the intended production database and SQLite as a fallback for simpler environments. Redis is used for cache and Channels infrastructure when available, but the README indicates graceful fallback to database cache and in-memory channels when Redis is absent.

11. **Async and background processing**
Real-time communication is handled through Channels consumers, while background work is handled by `django-background-tasks` through `users/tasks.py` and scheduled maintenance commands like story cleanup. This separates immediate request/response behavior from deferred or periodic work.

12. **Platform and deployment boundary**
The repo is container-ready with `Dockerfile`, `docker-compose.yml`, and GitHub Actions tests workflow, so deployment is treated as part of the architecture. The project also includes internationalization, secure headers, and environment-driven configuration in `settings.py`, which makes runtime behavior depend heavily on deployment environment rather than hardcoded defaults.

Main entry points: [`socialmediaproject/urls.py`](https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/urls.py) (Main router), [`templates`](https://github.com/neoastra303/socialmedia-app/tree/main/templates) (Shared templates), [`users`](https://github.com/neoastra303/socialmedia-app/tree/main/users) (Users), [`posts`](https://github.com/neoastra303/socialmedia-app/tree/main/posts) (Posts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_project["Project core"]
  node_node_asgi["ASGI entry<br/>entrypoint<br/>[asgi.py]"]
  node_node_urls["Main router<br/>[urls.py]"]
  node_node_routing["WS router<br/>channel routing<br/>[routing.py]"]
  node_node_settings["Settings<br/>config<br/>[settings.py]"]
end

subgraph group_group_features["Feature apps"]
  node_node_users["Users<br/>identity app"]
  node_node_posts["Posts<br/>content app"]
  node_node_dm["Messages<br/>chat app"]
  node_node_notifications["Notifications<br/>realtime app"]
  node_node_reports["Reports<br/>moderation app"]
  node_node_search["Search"]
  node_node_searchapp["Search UI<br/>search frontend"]
  node_node_background["Background work<br/>async jobs<br/>[tasks.py]"]
end

subgraph group_group_platform["Platform"]
  node_node_middleware["Middleware<br/>cross-cutting"]
  node_node_templates["Shared templates<br/>presentation"]
  node_node_static["Static assets<br/>frontend assets"]
  node_node_utils["File utils<br/>shared utility<br/>[file_validation.py]"]
end

node_node_asgi -->|"loads"| node_node_settings
node_node_asgi -->|"serves WS"| node_node_routing
node_node_asgi -->|"serves HTTP"| node_node_urls
node_node_urls -->|"routes"| node_node_users
node_node_urls -->|"routes"| node_node_posts
node_node_urls -->|"routes"| node_node_dm
node_node_urls -->|"routes"| node_node_notifications
node_node_urls -->|"routes"| node_node_reports
node_node_urls -->|"routes"| node_node_searchapp
node_node_routing -->|"ws consumers"| node_node_dm
node_node_routing -->|"ws consumers"| node_node_notifications
node_node_posts -->|"authored by"| node_node_users
node_node_posts -->|"validates media"| node_node_utils
node_node_notifications -->|"targets users"| node_node_users
node_node_dm -->|"between users"| node_node_users
node_node_reports -->|"reports content"| node_node_posts
node_node_reports -->|"reports users"| node_node_users
node_node_search -->|"indexes"| node_node_posts
node_node_search -->|"indexes"| node_node_users
node_node_searchapp -->|"presents"| node_node_search
node_node_templates -->|"renders"| node_node_users
node_node_templates -->|"renders"| node_node_posts
node_node_templates -->|"renders"| node_node_dm
node_node_templates -->|"renders"| node_node_notifications
node_node_templates -->|"renders"| node_node_reports
node_node_templates -->|"renders"| node_node_searchapp
node_node_static -->|"supports UI"| node_node_templates
node_node_middleware -->|"configured by"| node_node_settings
node_node_background -->|"scheduled by"| node_node_users
node_node_posts -->|"cleanup job"| node_node_background

click node_node_asgi "https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/asgi.py"
click node_node_urls "https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/urls.py"
click node_node_routing "https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/routing.py"
click node_node_settings "https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/settings.py"
click node_node_users "https://github.com/neoastra303/socialmedia-app/tree/main/users"
click node_node_posts "https://github.com/neoastra303/socialmedia-app/tree/main/posts"
click node_node_dm "https://github.com/neoastra303/socialmedia-app/tree/main/direct_messages"
click node_node_notifications "https://github.com/neoastra303/socialmedia-app/tree/main/notifications"
click node_node_reports "https://github.com/neoastra303/socialmedia-app/tree/main/reports"
click node_node_search "https://github.com/neoastra303/socialmedia-app/tree/main/search"
click node_node_searchapp "https://github.com/neoastra303/socialmedia-app/tree/main/searchapp"
click node_node_middleware "https://github.com/neoastra303/socialmedia-app/tree/main/middleware"
click node_node_templates "https://github.com/neoastra303/socialmedia-app/tree/main/templates"
click node_node_static "https://github.com/neoastra303/socialmedia-app/tree/main/static"
click node_node_utils "https://github.com/neoastra303/socialmedia-app/blob/main/utils/file_validation.py"
click node_node_background "https://github.com/neoastra303/socialmedia-app/blob/main/users/tasks.py"

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_node_asgi,node_node_urls,node_node_routing,node_node_settings toneBlue
class node_node_users,node_node_posts,node_node_dm,node_node_notifications,node_node_reports,node_node_search,node_node_searchapp,node_node_background toneAmber
class node_node_middleware,node_node_templates,node_node_static,node_node_utils toneMint
```

## Components

### Project core

Django project configuration, routing, and runtime entrypoints.

- [ASGI entry](https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/asgi.py): entrypoint · Async application entrypoint for Django/Channels. · `socialmediaproject/asgi.py`
- [Main router](https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/urls.py): router · HTTP URL configuration for the whole project. · `socialmediaproject/urls.py`
- [WS router](https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/routing.py): channel routing · WebSocket route wiring for Channels consumers. · `socialmediaproject/routing.py`
- [Settings](https://github.com/neoastra303/socialmedia-app/blob/main/socialmediaproject/settings.py): config · Central Django configuration and environment-driven runtime settings. · `socialmediaproject/settings.py`

### Feature apps

Domain apps that implement the main product capabilities.

- [Users](https://github.com/neoastra303/socialmedia-app/tree/main/users): identity app · Authentication, profiles, privacy, blocking, follows, settings, and account lifecycle. · `users`
- [Posts](https://github.com/neoastra303/socialmedia-app/tree/main/posts): content app · Feeds, posts, comments, reactions, bookmarks, stories, media, and serializers. · `posts`
- [Messages](https://github.com/neoastra303/socialmedia-app/tree/main/direct_messages): chat app · Direct messaging views, forms, models, and WebSocket consumers. · `direct_messages`
- [Notifications](https://github.com/neoastra303/socialmedia-app/tree/main/notifications): realtime app · Persisted notifications plus live push consumers and list views. · `notifications`
- [Reports](https://github.com/neoastra303/socialmedia-app/tree/main/reports): moderation app · Abuse reporting and moderation workflows. · `reports`
- [Search](https://github.com/neoastra303/socialmedia-app/tree/main/search): search backend · Backend search logic and data access. · `search`
- [Search UI](https://github.com/neoastra303/socialmedia-app/tree/main/searchapp): search frontend · Search presentation layer and search result templates. · `searchapp`
- [Background work](https://github.com/neoastra303/socialmedia-app/blob/main/users/tasks.py): async jobs · Deferred tasks and scheduled cleanup jobs. · `users/tasks.py`

### Platform

Shared middleware, utilities, templates, and deployment assets.

- [Middleware](https://github.com/neoastra303/socialmedia-app/tree/main/middleware): cross-cutting · Exception handling and rate limiting for request processing. · `middleware`
- [Shared templates](https://github.com/neoastra303/socialmedia-app/tree/main/templates): presentation · Global base layout and shared server-rendered templates. · `templates`
- [Static assets](https://github.com/neoastra303/socialmedia-app/tree/main/static): frontend assets · CSS and JavaScript served by the project. · `static`
- [File utils](https://github.com/neoastra303/socialmedia-app/blob/main/utils/file_validation.py): shared utility · Reusable upload and file validation helpers. · `utils/file_validation.py`

## Connections

- ASGI entry → Settings: loads · ASGI runtime uses project configuration.
- ASGI entry → WS router: serves WS · Channels connects ASGI to websocket routes.
- ASGI entry → Main router: serves HTTP · ASGI exposes the main request router.
- Main router → Users: routes · Main HTTP router includes account and profile URLs.
- Main router → Posts: routes · Main HTTP router includes content URLs.
- Main router → Messages: routes · Main HTTP router includes messaging URLs.
- Main router → Notifications: routes · Main HTTP router includes notification URLs.
- Main router → Reports: routes · Main HTTP router includes moderation URLs.
- Main router → Search UI: routes · Main HTTP router includes search UI URLs.
- WS router → Messages: ws consumers · WebSocket routes connect to direct message consumers.
- WS router → Notifications: ws consumers · WebSocket routes connect to notification consumers.
- Posts → Users: authored by · Posts depend on user identity and ownership.
- Posts → File utils: validates media · Content uploads reuse shared file validation.
- Notifications → Users: targets users · Notifications are associated with user accounts.
- Messages → Users: between users · Messaging is anchored in user accounts.
- Reports → Posts: reports content · Moderation workflows act on content objects.
- Reports → Users: reports users · Moderation workflows also cover account abuse.
- Search → Posts: indexes · Search backend queries content data.
- Search → Users: indexes · Search backend queries people and profiles.
- Search UI → Search: presents · Search UI renders backend search results.
- Shared templates → Users: renders · Shared templates include account pages.
- Shared templates → Posts: renders · Shared templates include post views.
- Shared templates → Messages: renders · Shared templates include message views.
- Shared templates → Notifications: renders · Shared templates include notification views.
- Shared templates → Reports: renders · Shared templates include moderation pages.
- Shared templates → Search UI: renders · Shared templates include search pages.
- Static assets → Shared templates: supports UI · Static CSS and JS back the server-rendered templates.
- Middleware → Settings: configured by · Middleware behavior is defined by project settings.
- Background work → Users: scheduled by · Background tasks support account lifecycle work.
- Posts → Background work: cleanup job · Story expiration is handled by scheduled maintenance.