How natea/socialcal works
Project type and purpose
• SocialCal is a full-stack, monolithic Django web application.
• Its core purpose is to scrape event data from various websites (and optionally enrich it via external APIs like Spotify or OpenAI), store it in a database, and expose those events to end users through both a web UI and a REST API.
File structure for architectural cues
• Top-level Django project (“socialcal”) with settings split by environment (base, development, production, test).
• Multiple Django apps under the project root:
– accounts (user account management + adapters)
– users (straightforward user model + admin)
– profiles (user profiles & preferences)
– events (scrapers, models, tasks, management commands)
– calendar_app (calendar view rendering)
– api (DRF serializers, views, URLs)
– core (home page, privacy/terms-of-service)
• Static assets in “static” and built/admin assets in “staticfiles.”
• Asynchronous tasks likely via Django-Celery or management commands (events/tasks.py, events/management/commands).
• Configuration files: Dockerfile, docker-entrypoint.sh, .env-dummy, render.yaml for deployment.
• Testing scaffolding: pytest, conftest.py, per-app tests.
Confirm technical stack and runtime behavior from README
• Python 3 + Django + Django REST Framework
• External integrations: OPENAI_API_KEY, SPOTIFY_CLIENT_ID / SECRET
• Single RDBMS (e.g., Postgres) behind Django ORM
• Webserver via manage.py runserver (development), containerized/WSGI in production
Main components
a. Client layer
– Web browser (user UI)
– Optional external clients consuming REST API (mobile apps, calendar apps)
b. Web tier
– NGINX (or similar) reverse proxy / Load Balancer
– WSGI server (Gunicorn / uWSGI) running Django
c. Django monolith
– URL Dispatcher → Django apps:
• accounts & users (auth, signup, login)
• profiles (profile CRUD, calendar visibility)
• events (scrapers, event model, tasks)
• calendar_app (month/day views, ICS generation)
• api (DRF endpoints for events, profiles)
• core (static pages)
– Settings module (base + env-specific overrides)
d. Background worker tier
– Celery worker / Django management commands
• Periodic or on-demand scrapers (crawl4ai, ical, site scrapers)
• Spotify enrichment, ICS generation tasks
e. Data tier
– Relational database (PostgreSQL or other)
– Static file storage (S3 or local FS for staticfiles/media)
f. External services
– Event source websites (HTTP scrapes)
– Spotify API
– OpenAI API (optional curation)
Relationships and data flows
• User → HTTP → NGINX → Gunicorn → Django URL router → views → ORM → Database → views → HTTP → User
• Django views / APIs may trigger Celery tasks or run scrapers via management commands
• Celery worker → scrapes external sites / calls Spotify or OpenAI → writes events to Database
• API clients consume serialized event data from DRF endpoints
• Calendar ICS feeds generated on-the-fly by calendar_app and served to clients
Architectural patterns and design principles
• Monolithic modularization (each Django app encapsulates a feature set)
• Layered architecture: Presentation (templates + JS) / Business logic (views, tasks) / Data (models, DB)
• Asynchronous processing of long-running jobs via Celery or Django commands
• Clear separation of concerns:
– “api” app for machine-readable interfaces
– “calendar_app” & templates for human-readable UI