dev-yvonne/events-system

1. Overall shape

- EventHub is a Django monolith with a multi-portal architecture: attendee, organizer, custom admin portal, and the standard Django admin.

- Core behavior is server-rendered through Django templates, with portal-specific JavaScript used for dynamic interactions and API calls.

2. Routing and portal boundaries

- config/urls.py delegates into separate URL sets for attendee, organizer, admin, and API surfaces.

- This is an important architectural boundary: each portal has its own templates, static assets, and page flows, while sharing the same backend models and auth system.

3. Core domain modules

- events/ is the central marketplace module: event creation, discovery, SEO pages, organizer APIs, checkout-related event logic, and seed data.

- bookings/ handles booking records, ticket lifecycle, and booking-related email workflows.

- payments/ manages payment orders, M-Pesa integration, verification, screenshots, and notification side effects.

- reviews/ covers event reviews and customer stories.

- subscriptions/ contains organizer plan logic and subscription services.

- notifications/ stores notification state and exposes notification views.

4. Identity and account subsystem

- accounts/ is the authentication and user-management boundary.

- It includes user profiles, Google auth, organizer verification, API tokens/keys, team-member relationships, presence tracking, and revenue metrics.

- The account model appears to support multiple roles and organization-oriented organizer accounts, which feeds the portal separation.

5. Data model and persistence

- The project uses Django ORM with extensive migrations in each app, indicating a relational schema as the main system of record.

- config/settings.py plus DATABASE_URL in the README imply SQLite for development and PostgreSQL in production.

- database_schema.dot suggests the schema has been documented explicitly, which is useful for domain/data diagramming.

6. Payment and ticketing flow

- The primary business flow is: attendee selects an event/tickets, creates a booking/order, initiates payment, and receives a confirmed booking/ticket after verification.

- payments/mpesa.py, payments/screenshot_verifier.py, and payments/screenshot_storage.py show that M-Pesa is a first-class payment rail, with manual/assisted verification support.

- bookings/email_service.py indicates booking confirmation and transactional email are part of the fulfillment path.

7. Organizer operations

- Organizers manage events, tickets, bookings, attendees, promotions, reviews, support, and scanner/check-in flows from frontend/templates/organizer/ and frontend/static/js/organizer/.

- events/api_organizer_views.py, admin_views.py, and organizer-specific JS suggest an operational console rather than a consumer-facing marketplace.

- Subscription state and billing views are part of this portal, tying organizer access to plan status.

8. Custom platform administration

- The repo has a dedicated admin portal under admin_views.py and frontend/templates/admin/, separate from Django’s built-in admin.

- This portal focuses on moderation and operations: users, organizers, events approvals, payments, bookings, tickets, reports, notifications, support, and settings.

- That separation matters architecturally because it reflects a business-ops layer above the domain apps.

9. Frontend structure

- The frontend is template-first, not an SPA: shared base templates plus portal-specific templates in frontend/templates/{attendee,organizer,admin,shared}.

- Static assets are similarly partitioned by portal in frontend/static/css and frontend/static/js, with shared helpers in frontend/static/js/shared/.

- This suggests a multi-page app enhanced with modular JavaScript services, fetch wrappers, and client-side UI state for carts, wishlist, auth, and dashboards.

10. Discovery, SEO, and public content

- events/seo_views.py, events/discovery.py, and frontend/templates/attendee/pages/* show a strong public-discovery layer.

- The README mentions /robots.txt, /sitemap.xml, and meta descriptions, so SEO is part of the public architecture rather than an afterthought.

- The homepage is content-heavy and likely uses prefetching/curated sections such as featured events, stats, testimonials, and newsletter blocks.

11. Cross-cutting services

- accounts/presence.py and frontend/static/js/shared/presence.js indicate live user/organizer presence features.

- payments/notification_utils.py and payments/organizer_notifications.py show internal notification fan-out from payment events.

- frontend/static/js/shared/* includes reusable browser services for auth, cart storage, wishlist storage, event API calls, and portal notifications.

12. Authentication and role handling

- Auth is spread across accounts/auth.py, accounts/auth_views.py, and accounts/google_auth.py, with shared login/register templates in frontend/templates/shared/auth/.

- The app supports role-specific experiences and likely role-based authorization checks across attendee, organizer, and admin surfaces.

- API key and team-member models imply some endpoints or operational tools are secured beyond simple session auth.

13. Operational and deployment shape

- Procfile, render.yaml, and vercel.json indicate deployment is configured for hosted environments, with the backend likely running as a Django app and static assets served separately or as part of deployment packaging.

- backend/staticfiles/ suggests collected/static build output is tracked for deployment.

- config/requirements.txt and top-level requirements.txt reinforce a Python runtime centered deployment.

14. How the pieces connect

- Browser requests enter Django through portal-specific URLs.

- Views read/write relational data through app models and migrations.

- Payment/order actions trigger M-Pesa integration and verification workflows.

- Successful bookings drive emails, notifications, and ticket state changes.

- The frontend layers consume backend-rendered pages plus JSON endpoints for dashboard and management interactions.