# sasin83/nayan architecture

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

- Interactive diagram: https://gitdiagram.com/sasin83/nayan
- Repository: https://github.com/sasin83/nayan

## Overview

1. **Overall shape**
   - This repository is a **Django web application** wrapped around a **separate face-recognition pipeline**.  
   - The web side handles user interaction, pages, and persistence; the `Project/` folder holds the computer-vision and enrollment scripts.

2. **Django platform boundary**
   - The Django project lives under `Nayan/` with the standard entry points: `manage.py`, `settings.py`, `urls.py`, `asgi.py`, and `wsgi.py`.
   - This is the main runtime for the browser-facing system and the HTTP request/response layer.

3. **Main app module**
   - The `Recognize/` app is the primary Django feature module.
   - It contains `views.py`, `urls.py`, `models.py`, `forms.py`, `admin.py`, and migrations, which indicates the normal MVC-like Django split: routing, page logic, form handling, and database-backed entities.

4. **UI and presentation layer**
   - Templates are under `Recognize/templates/recognize/` and static assets under `Recognize/static/recognize/`.
   - The app includes screens for the landing page, gallery, upload flow, and recognition-related pages such as `screens.html` and `screens_parallel.html`.
   - This suggests the browser UI is the main operator interface for submitting images and browsing recognized people.

5. **Computer-vision / recognition subsystem**
   - The `Project/` directory is the non-Django processing layer.
   - Key scripts include:
     - `Train.py` for encoding/training face data
     - `Recognizer.py` for identification
     - `Register.py` for logging recognized faces
     - `Face Detector.py` for face detection
   - This subsystem is the core domain engine and is separate from the web app.

6. **Data flow from images to identity**
   - Training uses labeled image files and produces pickle artifacts such as `CriminalSet.pk` and `MissingSet.pk`.
   - The README notes a filename convention like `ID.Name.jpeg`, which means identity is derived from file naming rather than a richer metadata system.
   - Recognition then consumes those trained encodings to compare an input face against known people.

7. **Persistence and artifacts**
   - The project uses multiple storage forms:
     - `db.sqlite3` for Django app data
     - `media/images/` for uploaded or processed images
     - pickle files (`*.pk`) for trained face encodings
     - CSV logging via `Register.py`
   - This means the architecture is split between relational app state and file-based machine-learning artifacts.

8. **Case categories / output organization**
   - There are separate data folders for **Criminal** and **Missing** faces, including `recognized/Criminal` and `recognized/Missing`.
   - That implies the recognition pipeline categorizes matches into distinct operational buckets rather than treating all identities uniformly.

9. **Operational logging and geolocation**
   - The README states that when a face is recognized, the system records the device’s IP-based geolocation and writes a dated CSV log.
   - Architecturally, this is a side-effect path attached to recognition, not just a classification result.

10. **External/runtime dependencies**
   - The repository is built around Python, Django, and face-recognition tooling that depends on `dlib`/`face_recognition`.
   - The included `Scripts/` folder and Windows executables show the development/runtime setup is Windows-oriented and likely uses a local Python virtual environment.

11. **System boundaries to show in a diagram**
   - A useful diagram should show:
     - browser users → Django views/templates
     - Django app → uploaded images / SQLite / media files
     - Django app → face-recognition scripts in `Project/`
     - training pipeline → pickle model artifacts
     - recognition pipeline → logged CSV output and recognized-image folders

12. **Architectural summary**
   - In short: this is a **Django front end plus file-based CV backend**.
   - The web app manages interaction and records; the recognition engine performs training and matching; persistence is split across SQLite, media storage, pickle models, and CSV logs.

Main entry points: [`Nayan/Recognize/views.py`](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/views.py) (Views), [`Nayan/Project/Recognizer.py`](https://github.com/sasin83/nayan/blob/master/Nayan/Project/Recognizer.py) (Recognizer), [`Nayan/Project/Train.py`](https://github.com/sasin83/nayan/blob/master/Nayan/Project/Train.py) (Train), [`Nayan/Nayan/settings.py`](https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/settings.py) (settings.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Django web"]
  node_manage_py["manage.py<br/>Django entrypoint<br/>[manage.py]"]
  node_settings_py["settings.py<br/>Django config<br/>[settings.py]"]
  node_project_urls["Project urls<br/>URL router<br/>[urls.py]"]
  node_asgi_wsgi["ASGI/WSGI<br/>deployment entry<br/>[asgi.py]"]
end

subgraph group_app["Recognize app"]
  node_recognize_urls["App urls<br/>app router<br/>[urls.py]"]
  node_views_py["Views<br/>request handlers<br/>[views.py]"]
  node_forms_py["Forms<br/>[forms.py]"]
  node_models_py["Models<br/>[models.py]"]
  node_admin_py["Admin<br/>[admin.py]"]
  node_templates["Templates<br/>presentation layer"]
  node_static_assets["Static assets<br/>ui assets"]
end

subgraph group_cv["CV pipeline"]
  node_train_py["Train<br/>[Train.py]"]
  node_detector_py["Face detector<br/>detection script<br/>[Face Detector.py]"]
  node_recognizer_py["Recognizer<br/>matching script<br/>[Recognizer.py]"]
  node_register_py["Register<br/>logging script<br/>[Register.py]"]
end

subgraph group_storage["Storage"]
  node_db_sqlite[("SQLite DB<br/>relational store<br/>[db.sqlite3]")]
  node_media_images["Media images<br/>file store"]
  node_criminal_pk["CriminalSet.pk<br/>face encodings<br/>[CriminalSet.pk]"]
  node_missing_pk["MissingSet.pk<br/>face encodings<br/>[MissingSet.pk]"]
  node_recognized_out["Recognized output<br/>result folders"]
  node_csv_logs["CSV logs<br/>event log"]
end

node_browser(("Browser users<br/>external actor"))

node_browser -->|"HTTP requests"| node_project_urls
node_project_urls -->|"dispatch"| node_recognize_urls
node_recognize_urls -->|"routes"| node_views_py
node_views_py -->|"render"| node_templates
node_views_py -->|"validate input"| node_forms_py
node_views_py -->|"read/write"| node_models_py
node_views_py -->|"store images"| node_media_images
node_models_py -->|"persist"| node_db_sqlite
node_admin_py -.->|"register"| node_models_py
node_views_py -->|"invoke"| node_recognizer_py
node_views_py -.->|"trigger training"| node_train_py
node_train_py -->|"detect faces"| node_detector_py
node_train_py -->|"build encodings"| node_criminal_pk
node_train_py -->|"build encodings"| node_missing_pk
node_recognizer_py -->|"load model"| node_criminal_pk
node_recognizer_py -->|"load model"| node_missing_pk
node_recognizer_py -->|"log match"| node_register_py
node_register_py -->|"append"| node_csv_logs
node_recognizer_py -->|"write outputs"| node_recognized_out
node_settings_py -.->|"configures"| node_db_sqlite
node_settings_py -.->|"media config"| node_media_images
node_manage_py -->|"bootstrap"| node_settings_py
node_asgi_wsgi -.->|"serve app"| node_project_urls

click node_manage_py "https://github.com/sasin83/nayan/blob/master/Nayan/manage.py"
click node_settings_py "https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/settings.py"
click node_project_urls "https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/urls.py"
click node_asgi_wsgi "https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/asgi.py"
click node_recognize_urls "https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/urls.py"
click node_views_py "https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/views.py"
click node_forms_py "https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/forms.py"
click node_models_py "https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/models.py"
click node_admin_py "https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/admin.py"
click node_templates "https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/templates/recognize"
click node_static_assets "https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/static/recognize"
click node_db_sqlite "https://github.com/sasin83/nayan/blob/master/Nayan/db.sqlite3"
click node_media_images "https://github.com/sasin83/nayan/tree/master/Nayan/media/images"
click node_criminal_pk "https://github.com/sasin83/nayan/blob/master/Nayan/Project/CriminalSet.pk"
click node_missing_pk "https://github.com/sasin83/nayan/blob/master/Nayan/Project/MissingSet.pk"
click node_recognized_out "https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/recognized"
click node_train_py "https://github.com/sasin83/nayan/blob/master/Nayan/Project/Train.py"
click node_detector_py "https://github.com/sasin83/nayan/blob/master/Nayan/Project/Face Detector.py"
click node_recognizer_py "https://github.com/sasin83/nayan/blob/master/Nayan/Project/Recognizer.py"
click node_register_py "https://github.com/sasin83/nayan/blob/master/Nayan/Project/Register.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_py,node_project_urls,node_asgi_wsgi toneBlue
class node_recognize_urls,node_views_py,node_forms_py,node_models_py,node_admin_py,node_templates,node_static_assets toneAmber
class node_train_py,node_detector_py,node_recognizer_py,node_register_py toneMint
class node_db_sqlite,node_media_images,node_criminal_pk,node_missing_pk,node_recognized_out,node_csv_logs toneRose
class node_browser toneNeutral
```

## Components

### Django web

HTTP entry points, routing, pages, and app logic.

- [manage.py](https://github.com/sasin83/nayan/blob/master/Nayan/manage.py): Django entrypoint · Project command entry for local management tasks. · `Nayan/manage.py`
- [settings.py](https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/settings.py): Django config · Project configuration for apps, middleware, and runtime settings. · `Nayan/Nayan/settings.py`
- [Project urls](https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/urls.py): URL router · Top-level Django routing for the project. · `Nayan/Nayan/urls.py`
- [ASGI/WSGI](https://github.com/sasin83/nayan/blob/master/Nayan/Nayan/asgi.py): deployment entry · Server interface modules for ASGI and WSGI deployment. · `Nayan/Nayan/asgi.py`

### Recognize app

Main Django feature module for recognition workflows.

- [App urls](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/urls.py): app router · Route definitions for the Recognize application. · `Nayan/Recognize/urls.py`
- [Views](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/views.py): request handlers · Page logic and orchestration for the recognition workflows. · `Nayan/Recognize/views.py`
- [Forms](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/forms.py): input forms · Django form definitions used by the web UI. · `Nayan/Recognize/forms.py`
- [Models](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/models.py): ORM models · Database-backed entities for the application. · `Nayan/Recognize/models.py`
- [Admin](https://github.com/sasin83/nayan/blob/master/Nayan/Recognize/admin.py): admin hooks · Django admin registration for app models. · `Nayan/Recognize/admin.py`
- [Templates](https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/templates/recognize): presentation layer · HTML screens for landing, upload, gallery, and recognition views. · `Nayan/Recognize/templates/recognize`
- [Static assets](https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/static/recognize): ui assets · CSS, JavaScript, and images used by the interface. · `Nayan/Recognize/static/recognize`

### CV pipeline

Standalone face detection, training, recognition, and logging scripts.

- [Train](https://github.com/sasin83/nayan/blob/master/Nayan/Project/Train.py): training script · Builds face encodings from labeled image sets. · `Nayan/Project/Train.py`
- [Face detector](https://github.com/sasin83/nayan/blob/HEAD/Nayan/Project/Face%20Detector.py): detection script · Locates faces in source images before recognition or training. · `Nayan/Project/Face Detector.py`
- [Recognizer](https://github.com/sasin83/nayan/blob/master/Nayan/Project/Recognizer.py): matching script · Compares detected faces against trained encodings. · `Nayan/Project/Recognizer.py`
- [Register](https://github.com/sasin83/nayan/blob/master/Nayan/Project/Register.py): logging script · Writes recognition events to CSV-like logs and side effects. · `Nayan/Project/Register.py`

### Storage

Database, media uploads, generated artifacts, and output folders.

- [SQLite DB](https://github.com/sasin83/nayan/blob/master/Nayan/db.sqlite3): relational store · Django application database. · `Nayan/db.sqlite3`
- [Media images](https://github.com/sasin83/nayan/tree/master/Nayan/media/images): file store · Uploaded and processed images persisted by the web app. · `Nayan/media/images`
- [CriminalSet.pk](https://github.com/sasin83/nayan/blob/master/Nayan/Project/CriminalSet.pk): face encodings · Serialized encodings for criminal identities. · `Nayan/Project/CriminalSet.pk`
- [MissingSet.pk](https://github.com/sasin83/nayan/blob/master/Nayan/Project/MissingSet.pk): face encodings · Serialized encodings for missing-person identities. · `Nayan/Project/MissingSet.pk`
- [Recognized output](https://github.com/sasin83/nayan/tree/master/Nayan/Recognize/recognized): result folders · Categorized recognized-image outputs for criminal and missing cases. · `Nayan/Recognize/recognized`
- **CSV logs**: event log · Dated recognition records and geolocation side effects.

### Other components

- **Browser users**: external actor · People interacting with the web interface.

## Connections

- Browser users → Project urls: HTTP requests · Users interact with the site through the Django routing layer.
- Project urls → App urls: dispatch · Top-level routes forward app-specific URLs to the Recognize module.
- App urls → Views: routes · App URL patterns map requests to view handlers.
- Views → Templates: render · Views serve the HTML screens for upload, gallery, and recognition flows.
- Views → Forms: validate input · Views use forms to process uploads and submissions.
- Views → Models: read/write · Views coordinate database-backed application state.
- Views → Media images: store images · Uploaded or processed images are persisted under media storage.
- Models → SQLite DB: persist · Django models are stored in the SQLite database.
- Admin → Models: register · Admin exposes model entities for management.
- Views → Recognizer: invoke · Web actions hand off recognition work to the CV pipeline.
- Views → Train: trigger training · The web layer can initiate or depend on training artifacts.
- Train → Face detector: detect faces · Training depends on face detection before encoding images.
- Train → CriminalSet.pk: build encodings · Training produces criminal face-encoding artifacts.
- Train → MissingSet.pk: build encodings · Training produces missing-person face-encoding artifacts.
- Recognizer → CriminalSet.pk: load model · Recognition compares against criminal encodings.
- Recognizer → MissingSet.pk: load model · Recognition compares against missing-person encodings.
- Recognizer → Register: log match · Recognition hands off successful matches for logging.
- Register → CSV logs: append · Recognition events are written to dated CSV-style logs.
- Recognizer → Recognized output: write outputs · Matched faces are organized into categorized output folders.
- settings.py → SQLite DB: configures · Project settings bind the app to its database and storage paths.
- settings.py → Media images: media config · Project settings define media handling for uploads and processed files.
- manage.py → settings.py: bootstrap · Manage entrypoint loads project settings for commands and local runtime.
- ASGI/WSGI → Project urls: serve app · Deployment entrypoints expose the Django project to the server.