How astrocamp/19th-fitcal works
Project type and purpose
• This is a full-stack web application (“FitCal”) built on Django (Python) with a JavaScript/CSS asset pipeline.
• Purpose: a calorie-balanced meal-ordering platform with separate domains (members, products, carts, orders, stores, pages, users).
File structure
• Top-level Django project folder:
• fitcal/ (ASGI, WSGI, settings, root URLs)
• manage.py, main.py
• Seven Django “apps” under root: carts, members, orders, pages, products, stores, users
• A “templates” directory mirroring each app for server-rendered HTML
• A src/ directory for front-end assets:
• src/scripts (flatpickr date-picker integration, input.js)
• src/styles (Tailwind CSS config & custom CSS files)
• Build and config files: package.json, tailwind.config.js, pyproject.toml, Makefile, .env-example
• PostgreSQL as the backing database
README for additional insights
• Python 3.13, Node.js ≥20
• Uses “uv” for virtual env, formatter, and running Django commands
• Front-end build/watch via npm run dev (esbuild & Tailwind)
• Database: PostgreSQL 17.4, configured via DATABASE_URL in .env
Main components and relationships
a. Client (Browser):
• Sends HTTP requests for pages, forms, assets
• Receives server-rendered HTML, CSS, JS
b. Front-end build pipeline (Node.js + esbuild + Tailwind):
• Takes src/scripts and src/styles → outputs bundled JS/CSS in static directory
• Run in watch mode (npm run dev) or one-off via Makefile/npm scripts
c. Django Application Server (ASGI):
• Entry point: fitcal/asgi.py
• URL router: fitcal/urls.py dispatches to each app’s urls.py
• Apps implement MVC pattern: models.py ←→ database, views.py ←→ templates, forms.py for validation
• Utilities, templatetags, and middleware in users/
d. Data store:
• PostgreSQL database
• Django ORM maps models in each app to relational tables under migrations/
e. Optional reverse proxy / load balancer (e.g., Nginx) in front of ASGI server for production (not in repo but standard)
Architectural patterns and design principles
• Monolithic, domain-driven Django MVC
• Separation of concerns by Django “apps” as bounded contexts
• Build pipeline loosely coupled: static assets built separately, then served by Django (or a CDN)
• Use of ASGI for async capabilities but primarily synchronous views
Detail
• Call out key config files (tailwind.config.js, package.json, pyproject.toml).
• Migrations folder under each app as part of the data layer evolution.