How bhargav-567/project-cms works
CSCP is a single Django monolith organized into domain-specific apps rather than separate services. The architecture is centered on server-rendered Django views and templates, with PostgreSQL for application state and the Windows filesystem for document storage.
At a high level, the system has four core boundaries:
1. Identity and authorization
2. Compliance document submission and approval workflow
3. Document retrieval/export and mailroom distribution
4. Audit, expiry, and operational automation
The browser-facing UI is built from Django templates in templates/ and theme/templates/, with styling compiled into static CSS under theme/static/css/dist/. There is no separate SPA frontend; request/response rendering happens in Django views.
Main runtime and platform pieces:
• Django app entrypoints: manage.py, cscp/cscp/urls.py, settings.py, wsgi.py, asgi.py
• Database: PostgreSQL
• File storage: local Windows filesystem, including document archives and log files
• Deployment target: Windows Server / Windows task scheduler, as indicated by run_expiry.bat and the README instructions
Subsystems
1. Accounts subsystem
• Located in cscp/accounts/
• Handles user registration/login forms, role-based permissions, and role setup
• Includes a management command setup_roles.py for seeding system roles such as Admin, HOD, L1, L2, and Mailroom
• permissions.py suggests custom permission checks beyond Django’s default auth
• This is the authorization boundary for the rest of the application: compliance, contractor, and workflow views depend on these roles
2. Contractor management subsystem
• Located in cscp/contractors/
• Manages contractor profiles and master document lifecycle
• Supports upload and review of foundational compliance documents such as PO, ESIC, EPF, and Labour License
• Includes check_expiry.py, which is invoked through scheduled automation to detect expiring documents and generate alerts
• The contractor side is the entry point for document intake before monthly compliance can proceed
3. Compliance subsystem
• Located in cscp/compliance/
• This is the main business workflow for statutory compliance
• Handles monthly compliance submission, review, rejection, and re-submission
• Has separate templates for different roles: contractor submission, HOD review, L1 review, L2 review, and role-specific dashboards
• Contains a parser.py, which likely supports document or query parsing related to compliance records
• Includes a smart_retrieval/ package, which is the document export/search engine
• Owns the structured monthly compliance model and workflow-facing forms/views
4. Smart retrieval/export subsystem
• Implemented under cscp/compliance/smart_retrieval/
• Decomposed into:
- parser.py: interprets query input
- query_builder.py: converts parsed terms into search filters
- file_collector.py: locates matching files in the archive
- zip_service.py: packages results for download
- orchestrator.py and smart_retrieval.py: coordinate the end-to-end retrieval flow
• This subsystem bridges human-friendly search requests and the filesystem-based document archive
• It is a file-oriented export pipeline, not a database search engine
5. Workflow subsystem
• Located in cscp/workflow/
• Encapsulates the approval-state logic and notification/expiry behaviors
• Contains state_machine.py, which is the clearest sign that status transitions are centralized here rather than scattered across views
• Includes expiry_service.py and notifications.py, supporting time-based reminders and workflow events
• This app likely acts as the domain engine for status progression and expiry tracking, while compliance provides the user-facing interaction layer
6. Audit subsystem
• Located in cscp/audit/
• Persists audit events in the database through models such as AuditLog
• Also writes operational logs to logs/audit.log
• Captures state transitions and review actions with metadata such as user, action type, previous/new status, timestamps, and IP address
• This is a cross-cutting observability and accountability layer used by workflow actions
7. Dashboard subsystem
• Located in cscp/dashboard/
• Aggregates data for role-based landing pages and summary views
• The templates suggest a main dashboard and separate role-specific dashboards
• This app is presentation-oriented and likely reads from compliance, workflow, and contractor data rather than owning core business state
Data and persistence boundaries
PostgreSQL stores:
• Users and roles
• Contractor records
• Master documents and monthly compliance records
• Workflow state/history
• Audit logs
Filesystem stores:
• Uploaded compliance documents
• Archived document trees organized by contractor, financial year, department, month, and document type
• Generated ZIP bundles for Smart Export
• Runtime logs under logs/
• Static assets and compiled CSS
This division is important: business metadata lives in the database, but the actual compliance artifacts are file-based. The application must keep DB state and filesystem contents aligned.
Key end-to-end flows
1. Authentication and role assignment
• Admin creates users
• setup_roles seeds predefined roles
• Role checks in accounts/permissions.py and Django auth determine which dashboard and workflow actions a user can access
2. Contractor master document onboarding
• Contractor submits initial documents through contractor/compliance views
• Reviewers approve or reject
• Approved documents become prerequisites for monthly compliance
• Rejection triggers a resubmission loop
3. Monthly compliance workflow
• Contractor submits monthly documents
• HOD reviews first, followed by L1 and L2
• Each approval/rejection updates persisted workflow state
• Workflow tracking is shown in role-specific templates and likely backed by the workflow app’s state machine
• Rejections preserve remarks and route the document back for correction
4. Smart Export
• User enters a natural-language query such as a document type, month, FY, or department
• The smart retrieval pipeline parses the query, translates it into filters, collects matching files from the archive, and returns a ZIP file
• This is a read-heavy filesystem operation layered over structured metadata and archive layout
5. Mailroom batch download
• Mailroom users access approved documents in bulk
• The flow is a retrieval/download use case, probably restricted to approved items only
• The associated template set indicates a distinct operational role with limited permissions
6. Expiry and notifications
• Scheduled tasks invoke management commands such as check_expiry
• run_expiry.bat is meant for Windows Task Scheduler automation
• Expiry logic likely checks documents against time windows like 7, 15, and 30 days and then logs or notifies
• This is an external scheduler-driven path, separate from interactive user requests
Cross-cutting concerns
• Role-based access control is pervasive across apps
• Audit logging is a first-class concern, not an afterthought
• Document expiry monitoring is automated through background commands and scheduled execution
• Templates are segmented by role and workflow stage, which reflects the business process rather than a generic page hierarchy
Repository structure signals
• Each domain app follows Django’s standard split: models.py, views.py, forms.py, urls.py, admin.py, and migrations
• That implies the system is organized around server-side MVC/MVT patterns
• management/commands/ folders show the system is not purely interactive; it also relies on administrative and scheduled command-line jobs
• The presence of theme/ indicates a separate presentation layer package for shared base templates and compiled assets
• utils/ contains shared helpers such as document tracking and email service functionality, which sit outside the main app boundaries
In diagram form, the most accurate mental model is:
Users by role → Django request router → app-specific views/forms → workflow and authorization checks → PostgreSQL for state + Windows filesystem for documents → optional ZIP generation / audit logging / scheduled expiry tasks
So this is best understood as a modular, server-rendered compliance management platform with a strong distinction between metadata in the database, documents on disk, and workflow state enforced through domain-specific Django apps.
Main entry points: contractors/views.py Contractors · compliance/views.py Compliance · state_machine.py Workflow · settings.py Settings
Components 23
Platform
Runtime, storage, and deployment boundaries
- manage.py · Command-line entrypoint for administrative tasks
cscp/manage.py - Project URLs · Top-level request routing for the Django monolith
cscp/cscp/urls.py - Settings · Project configuration and app wiring
cscp/cscp/settings.py - WSGI/ASGI · Server adapters for synchronous and async execution
cscp/cscp/wsgi.py - PostgreSQL · Stores users, contractors, compliance records, workflow state, and audit logs
- Windows FS · Stores compliance archives, uploaded documents, logs, and generated bundles
Identity
Authentication and permissions
- Accounts · User registration, login, role setup, and permission checks
cscp/accounts/views.py - Role setup · Seeds predefined roles such as Admin, HOD, L1, L2, and Mailroom
cscp/accounts/management/commands/setup_roles.py - Permissions · Custom authorization checks used across the application
cscp/accounts/permissions.py
Compliance
Contractor intake, submissions, and retrieval
- Contractors · Contractor profiles, master documents, and expiry checks
cscp/contractors/views.py - Master docs · Onboarding and review of foundational compliance documents
cscp/contractors/models.py - Expiry check · Detects expiring contractor documents for alerts and logs
cscp/contractors/management/commands/check_expiry.py - Compliance · Monthly submission, review, rejection, and resubmission flow
cscp/compliance/views.py - Monthly review · Role-based review screens for contractor, HOD, L1, and L2 actions
cscp/templates/compliance/monthly_review.html - Smart retrieval · Parses search intent, collects archive files, and builds ZIP exports
cscp/compliance/smart_retrieval/orchestrator.py
Workflow
State transitions, expiry, and notifications
- Workflow · Centralizes approval state transitions and time-based workflow behavior
cscp/workflow/state_machine.py - State machine · Defines workflow status transitions and progression rules
cscp/workflow/state_machine.py - Expiry service · Coordinates expiry-related workflow actions and reminders
cscp/workflow/expiry_service.py - Notifications · Sends workflow and expiry alerts
cscp/workflow/notifications.py
Operations
Audit, dashboard, and shared presentation
- Audit · Captures review actions and state transitions for accountability
cscp/audit/views.py - Audit log · Persists audit records in the database and writes operational logs
cscp/audit/models.py - Dashboard · Role-based landing pages and summary views
cscp/dashboard/views.py - Theme · Shared base templates and compiled static styles
cscp/theme/templates/base.html
Connections 36
- manage.py → Project URLs: boots app
- Settings → Accounts: installs
- Settings → Contractors: installs
- Settings → Compliance: installs
- Settings → Workflow: installs
- Settings → Audit: installs
- Settings → Dashboard: installs
- Project URLs → Accounts: routes to
- Project URLs → Contractors: routes to
- Project URLs → Compliance: routes to
- Project URLs → Dashboard: routes to
- Accounts → Role setup: seeds roles
- Accounts → Permissions: enforces
- Accounts → PostgreSQL: stores users
- Contractors → Master docs: manages
- Contractors → Expiry check: runs command
- Contractors → Windows FS: reads/writes docs
- Contractors → PostgreSQL: stores contractor data
- Compliance → Monthly review: renders
- Compliance → Smart retrieval: exports via
- Compliance → Workflow: delegates state
- Compliance → PostgreSQL: stores submissions
- Smart retrieval → Windows FS: collects files
- Smart retrieval → PostgreSQL: uses metadata
- Workflow → State machine: centralizes
- Workflow → Expiry service: runs expiry logic
- Workflow → Notifications: emits alerts
- Workflow → PostgreSQL: persists state
- Audit → Audit log: records events
- Audit → PostgreSQL: stores logs
- Audit → Windows FS: writes log file
- Dashboard → Theme: uses templates
- Dashboard → Compliance: summarizes
- Dashboard → Contractors: summarizes
- Dashboard → Workflow: summarizes
- WSGI/ASGI → Project URLs: serves