# vitorfs/parsifal architecture

> Architecture diagram of the GitHub repository vitorfs/parsifal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitorfs/parsifal
- Repository: https://github.com/vitorfs/parsifal

## Overview

Parsifal is a single Django monolith organized as a set of domain apps around one central workflow: planning, conducting, and reporting systematic literature reviews. The repository is not split into services; instead, the architecture is a layered Django project with shared settings, shared templates/static assets, and app-specific models/views/templates.

The top-level project layer lives under `parsifal/` and provides the Django bootstrap: `settings/` for environment-specific configuration, `urls.py` for route composition, and `wsgi.py` for deployment. The README and scripts show typical production packaging through Gunicorn + Nginx + Supervisor, with PostgreSQL as the primary database and SQLite supported locally.

The core business boundary is the `reviews` app, which acts as the hub for review lifecycle management. It owns the review list/create/detail screens and then delegates into subdomains under `reviews/planning`, `reviews/conducting`, `reviews/reporting`, and `reviews/settings`. This structure is important for diagramming because the review workflow is intentionally segmented by phase rather than by technical layer.

`reviews/planning` models and UI cover protocol definition: research questions, PICOC/keywords, inclusion/exclusion criteria, data extraction fields, quality assessment questions, search strings, and sources. Its templates and JavaScript indicate a rich server-rendered interface with client-side enhancement for editing review protocol artifacts.

`reviews/conducting` is the operational phase where studies are imported, searched, screened, deduplicated, and assessed. The templates and JS files show separate screens for importing studies, search results, study selection, duplicate detection, article details, data extraction, and quality assessment. This is the main transactional path where review data is transformed from protocol inputs into screened studies.

`reviews/reporting` is the output phase. It packages reporting views and an export module, suggesting generation of downloadable review outputs from the accumulated review data. In an architecture diagram, this is the downstream consumer of the planning/conducting data model.

`reviews/settings` provides review-level administrative controls such as review settings and delete flows. This is a boundary around lifecycle/configuration operations, distinct from the scientific workflow itself.

`authentication` and `accounts` together manage user identity and profile data. `authentication` contains the custom user/profile model, signup forms, validators, and backend logic; migrations show historical support for external account tokens like Mendeley and Dropbox, plus public email settings. `accounts` handles profile editing, email preferences, and profile pictures. These modules form the identity boundary for the rest of the system.

`invites` is a collaboration/access-control subsystem. It manages invite records, email generation, user invite lists, and a “manage access” view, so reviews can be shared with collaborators. For diagramming, this sits between authenticated users and review ownership/permissions.

`library` is a separate document management area for folders, documents, and shared folders. It has its own models, forms, views, templates, and JavaScript, so it should be shown as an adjacent authenticated workspace rather than part of the review workflow. It likely serves as a personal/shared reference repository for researchers.

`blog`, `help`, and `core` are the public-facing content areas. `core` provides home/about/support pages and shared context processors; `blog` serves articles and sitemap support; `help` serves article/category/search content with its own sitemap. These are distinct from the authenticated application and can be drawn as a public content boundary.

A few utility and integration pieces matter architecturally: `utils/elsevier/client.py` suggests an external Elsevier API integration for study metadata/search; `utils/recaptcha.py` indicates bot protection on public forms; and `utils/ipaddress.py`, `mask.py`, and `version.py` are shared helpers. The presence of `sitemaps.py` in multiple apps shows SEO-oriented public content generation.

The UI stack is server-rendered Django templates with per-app static JavaScript and a shared global static layer. Bootstrap 3.4 and jQuery 3.6 are the main client-side technologies, with app-specific JS enhancing forms and dynamic review screens rather than a standalone SPA.

Operationally, the repository includes management commands under `core/management/commands` for environment/release tasks, plus a test suite organized per app and GitHub Actions workflows for tox, code coverage, and CodeQL analysis. For an architecture diagram, the main flow is: browser requests enter Django, route into the appropriate app, app logic reads/writes PostgreSQL, and certain features integrate with external services or email-based collaboration.

Main entry points: [`parsifal/urls.py`](https://github.com/vitorfs/parsifal/blob/dev/parsifal/urls.py) (URL router), [`parsifal/apps/reviews`](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews) (Reviews), [`parsifal/apps/core`](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/core) (Core), [`parsifal/apps/authentication`](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/authentication) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Django project"]
  node_manage_py["manage.py<br/>Django entrypoint<br/>[manage.py]"]
  node_settings_pkg["Settings<br/>config layer"]
  node_root_urls["URL router<br/>route composition<br/>[urls.py]"]
  node_base_templates["Base UI<br/>shared templates"]
  node_static_assets["Shared assets<br/>static UI"]
end

subgraph group_public["Public content"]
  node_core_app["Core<br/>public shell"]
  node_blog_app["Blog<br/>public content"]
  node_help_app["Help<br/>support content"]
end

subgraph group_identity["Identity & access"]
  node_auth_app["Auth<br/>user model"]
  node_accounts_app["Accounts<br/>profile UI"]
  node_invites_app["Invites<br/>access control"]
end

subgraph group_reviews["Review workflow"]
  node_reviews_app["Reviews<br/>workflow hub"]
  node_planning_app["Planning<br/>protocol phase"]
  node_conducting_app["Conducting<br/>execution phase"]
  node_reporting_app["Reporting<br/>export phase"]
  node_review_settings_app["Review settings<br/>admin phase"]
end

subgraph group_workspace["Reference workspace"]
  node_library_app["Library<br/>document workspace"]
end

subgraph group_ops["Ops & integrations"]
  node_elsevier_client["Elsevier API<br/>external integration<br/>[client.py]"]
  node_recaptcha_util["reCAPTCHA<br/>bot protection<br/>[recaptcha.py]"]
end

node_manage_py -->|"bootstraps"| node_settings_pkg
node_manage_py -->|"runs"| node_root_urls
node_root_urls -->|"routes"| node_core_app
node_root_urls -->|"routes"| node_blog_app
node_root_urls -->|"routes"| node_help_app
node_root_urls -->|"routes"| node_auth_app
node_root_urls -->|"routes"| node_accounts_app
node_root_urls -->|"routes"| node_invites_app
node_root_urls -->|"routes"| node_reviews_app
node_root_urls -->|"routes"| node_library_app
node_core_app -->|"renders"| node_base_templates
node_core_app -->|"serves"| node_static_assets
node_auth_app -->|"supports"| node_accounts_app
node_invites_app -->|"checks users"| node_auth_app
node_reviews_app -->|"delegates"| node_planning_app
node_reviews_app -->|"delegates"| node_conducting_app
node_reviews_app -->|"delegates"| node_reporting_app
node_reviews_app -->|"delegates"| node_review_settings_app
node_reviews_app -->|"shares access"| node_invites_app
node_planning_app -.->|"searches"| node_elsevier_client
node_conducting_app -.->|"imports"| node_elsevier_client
node_core_app -.->|"protects"| node_recaptcha_util
node_library_app -->|"requires login"| node_auth_app
node_reporting_app -->|"exports from"| node_reviews_app

click node_manage_py "https://github.com/vitorfs/parsifal/blob/dev/manage.py"
click node_settings_pkg "https://github.com/vitorfs/parsifal/tree/dev/parsifal/settings"
click node_root_urls "https://github.com/vitorfs/parsifal/blob/dev/parsifal/urls.py"
click node_base_templates "https://github.com/vitorfs/parsifal/tree/dev/parsifal/templates"
click node_static_assets "https://github.com/vitorfs/parsifal/tree/dev/parsifal/static"
click node_core_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/core"
click node_blog_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/blog"
click node_help_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/help"
click node_auth_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/authentication"
click node_accounts_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/accounts"
click node_invites_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/invites"
click node_reviews_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews"
click node_planning_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/planning"
click node_conducting_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/conducting"
click node_reporting_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/reporting"
click node_review_settings_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/settings"
click node_library_app "https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/library"
click node_elsevier_client "https://github.com/vitorfs/parsifal/blob/dev/parsifal/utils/elsevier/client.py"
click node_recaptcha_util "https://github.com/vitorfs/parsifal/blob/dev/parsifal/utils/recaptcha.py"

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 node_manage_py,node_settings_pkg,node_root_urls,node_base_templates,node_static_assets toneBlue
class node_core_app,node_blog_app,node_help_app toneAmber
class node_auth_app,node_accounts_app,node_invites_app toneMint
class node_reviews_app,node_planning_app,node_conducting_app,node_reporting_app,node_review_settings_app toneRose
class node_library_app toneIndigo
class node_elsevier_client,node_recaptcha_util toneTeal
```

## Components

### Django project

Bootstrap, settings, routes, templates, and shared assets.

- [manage.py](https://github.com/vitorfs/parsifal/blob/dev/manage.py): Django entrypoint · Command-line entry for management tasks and local execution. · `manage.py`
- [Settings](https://github.com/vitorfs/parsifal/tree/dev/parsifal/settings): config layer · Environment-specific Django configuration for base, local, production, and tests. · `parsifal/settings`
- [URL router](https://github.com/vitorfs/parsifal/blob/dev/parsifal/urls.py): route composition · Top-level URL dispatcher composing all app routes. · `parsifal/urls.py`
- [Base UI](https://github.com/vitorfs/parsifal/tree/dev/parsifal/templates): shared templates · Global templates, layout, auth screens, and error pages. · `parsifal/templates`
- [Shared assets](https://github.com/vitorfs/parsifal/tree/dev/parsifal/static): static UI · Global CSS, JavaScript, fonts, and browser assets. · `parsifal/static`

### Public content

Unauthenticated pages and SEO-oriented content.

- [Core](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/core): public shell · Home, about, support pages plus shared context processors and release commands. · `parsifal/apps/core`
- [Blog](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/blog): public content · Article pages and sitemap-backed blog content. · `parsifal/apps/blog`
- [Help](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/help): support content · Article, category, and search help content with sitemap support. · `parsifal/apps/help`

### Identity & access

Users, profiles, invites, and session-adjacent access control.

- [Auth](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/authentication): user model · Custom user/profile model, signup forms, validators, and authentication backend. · `parsifal/apps/authentication`
- [Accounts](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/accounts): profile UI · Profile editing, email preferences, and picture management. · `parsifal/apps/accounts`
- [Invites](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/invites): access control · Invite records, email generation, and access management for collaborators. · `parsifal/apps/invites`

### Review workflow

Core systematic review lifecycle, split by phase.

- [Reviews](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews): workflow hub · Review list/create/detail hub coordinating the full systematic review lifecycle. · `parsifal/apps/reviews`
- [Planning](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/planning): protocol phase · Review protocol definition: questions, PICOC, criteria, extraction fields, quality checks, search strings, and sources. · `parsifal/apps/reviews/planning`
- [Conducting](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/conducting): execution phase · Import, search, deduplicate, screen, extract, and assess studies. · `parsifal/apps/reviews/conducting`
- [Reporting](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/reporting): export phase · Reporting views and export generation from accumulated review data. · `parsifal/apps/reviews/reporting`
- [Review settings](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/reviews/settings): admin phase · Review-level configuration and delete flows. · `parsifal/apps/reviews/settings`

### Reference workspace

Standalone document library for researchers.

- [Library](https://github.com/vitorfs/parsifal/tree/dev/parsifal/apps/library): document workspace · Folders, documents, and shared folders for researcher reference material. · `parsifal/apps/library`

### Ops & integrations

Deployment packaging, external APIs, and utility services.

- [Elsevier API](https://github.com/vitorfs/parsifal/blob/dev/parsifal/utils/elsevier/client.py): external integration · External metadata/search integration used by review tooling. · `parsifal/utils/elsevier/client.py`
- [reCAPTCHA](https://github.com/vitorfs/parsifal/blob/dev/parsifal/utils/recaptcha.py): bot protection · Shared anti-bot utility for public forms. · `parsifal/utils/recaptcha.py`

## Connections

- manage.py → Settings: bootstraps · Loads Django settings for commands and runtime.
- manage.py → URL router: runs · Starts the project command environment and route resolution.
- URL router → Core: routes · Dispatches public shell pages.
- URL router → Blog: routes · Dispatches blog content.
- URL router → Help: routes · Dispatches help content.
- URL router → Auth: routes · Dispatches authentication flows.
- URL router → Accounts: routes · Dispatches profile screens.
- URL router → Invites: routes · Dispatches invite management.
- URL router → Reviews: routes · Dispatches review workflow hub.
- URL router → Library: routes · Dispatches document workspace.
- Core → Base UI: renders · Uses shared layout and page chrome.
- Core → Shared assets: serves · Uses global styling and scripts.
- Auth → Accounts: supports · Provides authenticated identity for profile management.
- Invites → Auth: checks users · Creates and validates collaboration access for authenticated users.
- Reviews → Planning: delegates · Splits the review lifecycle into the planning phase.
- Reviews → Conducting: delegates · Splits the review lifecycle into the conducting phase.
- Reviews → Reporting: delegates · Splits the review lifecycle into the reporting phase.
- Reviews → Review settings: delegates · Separates lifecycle/configuration operations.
- Reviews → Invites: shares access · Connects reviews to collaboration and permissions.
- Planning → Elsevier API: searches · Uses external metadata/search integration when building protocol and study inputs.
- Conducting → Elsevier API: imports · Consumes external study metadata and search results.
- Core → reCAPTCHA: protects · Applies bot protection to public-facing forms.
- Library → Auth: requires login · Authenticated workspace for personal/shared documents.
- Reporting → Reviews: exports from · Downstream consumer of review data and lifecycle state.