# bhargav-567/project-cms architecture

> Architecture diagram of the GitHub repository bhargav-567/project-cms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhargav-567/project-cms
- Repository: https://github.com/bhargav-567/project-cms

## Overview

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: [`cscp/contractors/views.py`](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/contractors/views.py) (Contractors), [`cscp/compliance/views.py`](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/compliance/views.py) (Compliance), [`cscp/workflow/state_machine.py`](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/workflow/state_machine.py) (Workflow), [`cscp/cscp/settings.py`](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/cscp/settings.py) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Platform"
  manage_py["manage.py<br/>django entrypoint<br/>[manage.py]"]
  project_urls["Project URLs<br/>router<br/>[urls.py]"]
  settings["Settings<br/>config<br/>[settings.py]"]
  wsgi_asgi["WSGI/ASGI<br/>runtime entrypoints<br/>[wsgi.py]"]
  postgres[("PostgreSQL<br/>database")]
  windows_fs[("Windows FS<br/>file storage")]
end

subgraph "Identity"
  accounts_app["Accounts<br/>auth app<br/>[views.py]"]
  role_setup["Role setup<br/>management command<br/>[setup_roles.py]"]
  permissions["Permissions<br/>policy<br/>[permissions.py]"]
end

subgraph "Compliance"
  contractors_app["Contractors<br/>intake app<br/>[views.py]"]
  master_docs["Master docs<br/>document lifecycle<br/>[models.py]"]
  expiry_check["Expiry check<br/>scheduled command<br/>[check_expiry.py]"]
  compliance_app["Compliance<br/>workflow app<br/>[views.py]"]
  monthly_review["Monthly review<br/>approval flow"]
  smart_retrieval["Smart retrieval<br/>export pipeline<br/>[orchestrator.py]"]
end

subgraph "Workflow"
  workflow_app["Workflow<br/>domain engine<br/>[state_machine.py]"]
  state_machine["State machine<br/>state logic<br/>[state_machine.py]"]
  expiry_service["Expiry service<br/>automation<br/>[expiry_service.py]"]
  notifications["Notifications<br/>eventing<br/>[notifications.py]"]
end

subgraph "Operations"
  audit_app["Audit<br/>observability app<br/>[views.py]"]
  audit_log[("Audit log<br/>event store<br/>[models.py]")]
  dashboard_app["Dashboard<br/>presentation app<br/>[views.py]"]
  theme["Theme<br/>presentation layer<br/>[base.html]"]
end

manage_py -->|"boots app"| project_urls
settings -->|"installs"| accounts_app
settings -->|"installs"| contractors_app
settings -->|"installs"| compliance_app
settings -->|"installs"| workflow_app
settings -->|"installs"| audit_app
settings -->|"installs"| dashboard_app
project_urls -->|"routes to"| accounts_app
project_urls -->|"routes to"| contractors_app
project_urls -->|"routes to"| compliance_app
project_urls -->|"routes to"| dashboard_app
accounts_app -.->|"seeds roles"| role_setup
accounts_app -->|"enforces"| permissions
accounts_app -->|"stores users"| postgres
contractors_app -->|"manages"| master_docs
contractors_app -.->|"runs command"| expiry_check
contractors_app -->|"reads/writes docs"| windows_fs
contractors_app -->|"stores contractor data"| postgres
compliance_app -->|"renders"| monthly_review
compliance_app -->|"exports via"| smart_retrieval
compliance_app -->|"delegates state"| workflow_app
compliance_app -->|"stores submissions"| postgres
smart_retrieval -->|"collects files"| windows_fs
smart_retrieval -.->|"uses metadata"| postgres
workflow_app -->|"centralizes"| state_machine
workflow_app -->|"runs expiry logic"| expiry_service
workflow_app -->|"emits alerts"| notifications
workflow_app -->|"persists state"| postgres
audit_app -->|"records events"| audit_log
audit_app -->|"stores logs"| postgres
audit_app -.->|"writes log file"| windows_fs
dashboard_app -->|"uses templates"| theme
dashboard_app -.->|"summarizes"| compliance_app
dashboard_app -.->|"summarizes"| contractors_app
dashboard_app -.->|"summarizes"| workflow_app
wsgi_asgi -->|"serves"| project_urls

click manage_py "https://github.com/bhargav-567/project-cms/blob/main/cscp/manage.py"
click project_urls "https://github.com/bhargav-567/project-cms/blob/main/cscp/cscp/urls.py"
click settings "https://github.com/bhargav-567/project-cms/blob/main/cscp/cscp/settings.py"
click wsgi_asgi "https://github.com/bhargav-567/project-cms/blob/main/cscp/cscp/wsgi.py"
click accounts_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/accounts/views.py"
click role_setup "https://github.com/bhargav-567/project-cms/blob/main/cscp/accounts/management/commands/setup_roles.py"
click permissions "https://github.com/bhargav-567/project-cms/blob/main/cscp/accounts/permissions.py"
click contractors_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/contractors/views.py"
click master_docs "https://github.com/bhargav-567/project-cms/blob/main/cscp/contractors/models.py"
click expiry_check "https://github.com/bhargav-567/project-cms/blob/main/cscp/contractors/management/commands/check_expiry.py"
click compliance_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/compliance/views.py"
click monthly_review "https://github.com/bhargav-567/project-cms/blob/main/cscp/templates/compliance/monthly_review.html"
click smart_retrieval "https://github.com/bhargav-567/project-cms/blob/main/cscp/compliance/smart_retrieval/orchestrator.py"
click workflow_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/workflow/state_machine.py"
click state_machine "https://github.com/bhargav-567/project-cms/blob/main/cscp/workflow/state_machine.py"
click expiry_service "https://github.com/bhargav-567/project-cms/blob/main/cscp/workflow/expiry_service.py"
click notifications "https://github.com/bhargav-567/project-cms/blob/main/cscp/workflow/notifications.py"
click audit_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/audit/views.py"
click audit_log "https://github.com/bhargav-567/project-cms/blob/main/cscp/audit/models.py"
click dashboard_app "https://github.com/bhargav-567/project-cms/blob/main/cscp/dashboard/views.py"
click theme "https://github.com/bhargav-567/project-cms/blob/main/cscp/theme/templates/base.html"

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 manage_py,project_urls,settings,wsgi_asgi,postgres,windows_fs toneBlue
class accounts_app,role_setup,permissions toneAmber
class contractors_app,master_docs,expiry_check,compliance_app,monthly_review,smart_retrieval toneMint
class workflow_app,state_machine,expiry_service,notifications toneRose
class audit_app,audit_log,dashboard_app,theme toneIndigo
```

## Components

### Platform

Runtime, storage, and deployment boundaries

- [manage.py](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/manage.py): django entrypoint · Command-line entrypoint for administrative tasks · `cscp/manage.py`
- [Project URLs](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/cscp/urls.py): router · Top-level request routing for the Django monolith · `cscp/cscp/urls.py`
- [Settings](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/cscp/settings.py): config · Project configuration and app wiring · `cscp/cscp/settings.py`
- [WSGI/ASGI](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/cscp/wsgi.py): runtime entrypoints · Server adapters for synchronous and async execution · `cscp/cscp/wsgi.py`
- **PostgreSQL**: database · Stores users, contractors, compliance records, workflow state, and audit logs
- **Windows FS**: file storage · Stores compliance archives, uploaded documents, logs, and generated bundles

### Identity

Authentication and permissions

- [Accounts](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/accounts/views.py): auth app · User registration, login, role setup, and permission checks · `cscp/accounts/views.py`
- [Role setup](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/accounts/management/commands/setup_roles.py): management command · Seeds predefined roles such as Admin, HOD, L1, L2, and Mailroom · `cscp/accounts/management/commands/setup_roles.py`
- [Permissions](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/accounts/permissions.py): policy · Custom authorization checks used across the application · `cscp/accounts/permissions.py`

### Compliance

Contractor intake, submissions, and retrieval

- [Contractors](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/contractors/views.py): intake app · Contractor profiles, master documents, and expiry checks · `cscp/contractors/views.py`
- [Master docs](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/contractors/models.py): document lifecycle · Onboarding and review of foundational compliance documents · `cscp/contractors/models.py`
- [Expiry check](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/contractors/management/commands/check_expiry.py): scheduled command · Detects expiring contractor documents for alerts and logs · `cscp/contractors/management/commands/check_expiry.py`
- [Compliance](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/compliance/views.py): workflow app · Monthly submission, review, rejection, and resubmission flow · `cscp/compliance/views.py`
- [Monthly review](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/templates/compliance/monthly_review.html): approval flow · Role-based review screens for contractor, HOD, L1, and L2 actions · `cscp/templates/compliance/monthly_review.html`
- [Smart retrieval](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/compliance/smart_retrieval/orchestrator.py): export pipeline · Parses search intent, collects archive files, and builds ZIP exports · `cscp/compliance/smart_retrieval/orchestrator.py`

### Workflow

State transitions, expiry, and notifications

- [Workflow](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/workflow/state_machine.py): domain engine · Centralizes approval state transitions and time-based workflow behavior · `cscp/workflow/state_machine.py`
- [State machine](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/workflow/state_machine.py): state logic · Defines workflow status transitions and progression rules · `cscp/workflow/state_machine.py`
- [Expiry service](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/workflow/expiry_service.py): automation · Coordinates expiry-related workflow actions and reminders · `cscp/workflow/expiry_service.py`
- [Notifications](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/workflow/notifications.py): eventing · Sends workflow and expiry alerts · `cscp/workflow/notifications.py`

### Operations

Audit, dashboard, and shared presentation

- [Audit](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/audit/views.py): observability app · Captures review actions and state transitions for accountability · `cscp/audit/views.py`
- [Audit log](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/audit/models.py): event store · Persists audit records in the database and writes operational logs · `cscp/audit/models.py`
- [Dashboard](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/dashboard/views.py): presentation app · Role-based landing pages and summary views · `cscp/dashboard/views.py`
- [Theme](https://github.com/bhargav-567/project-cms/blob/HEAD/cscp/theme/templates/base.html): presentation layer · Shared base templates and compiled static styles · `cscp/theme/templates/base.html`

## Connections

- 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
