# rockeyyabraham/fir-system architecture

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

- Interactive diagram: https://gitdiagram.com/rockeyyabraham/fir-system
- Repository: https://github.com/rockeyyabraham/fir-system

## Overview

1. **Overall shape**
   - This is a **server-rendered Flask application** for FIR management, not a client-heavy SPA.
   - The core runtime is Python/Flask, with HTML templates rendered on the server and a small amount of JavaScript/CSS for UI behavior.

2. **Main entry point and request handling**
   - `app.py` is the central controller layer.
   - It defines the HTTP routes for login/logout and the admin/officer workflows, then delegates actual data work to `backend.py`.
   - The app uses Flask sessions to keep track of the logged-in officer’s identity, station, and role.

3. **Authentication and access control boundary**
   - Login is based on a **composite identity**: officer ID + station ID + password.
   - After authentication, session state drives role-based access:
     - **admin** can add/remove officers, view officers, view FIRs, and close/update FIRs.
     - **officer** access is intended for operational FIR work and profile views.
   - Passwords are handled with Werkzeug hashing, so plaintext credentials are not stored.

4. **Business logic layer**
   - `backend.py` is the service layer that sits between Flask routes and the database.
   - It contains the domain operations for:
     - officer validation and role lookup
     - adding/removing officers
     - creating, reading, updating, and closing FIRs
     - complainant creation
   - In the current repo state, this layer is mostly a skeleton, but architecturally it is the main boundary for business rules.

5. **Persistence layer**
   - `database.py` is the database configuration/connection boundary.
   - The repo includes local database artifacts (`fir.db`, `fir_system.db`) and an SQL file (`new1.sql`), which strongly suggests a **SQLite-backed** setup for development.
   - The intended schema includes:
     - officers
     - firs
     - complainants
     - fir_complainants as a junction table
   - This means FIRs can be linked to complainants, and officers are associated with stations and roles.

6. **Domain data flow**
   - A typical flow is:
     1. user logs in via `login.html`
     2. `app.py` validates credentials through `backend.py`
     3. session is populated with officer/station/role
     4. user is routed to admin or officer dashboard templates
     5. actions like create/view/close FIR call backend functions
     6. backend reads/writes the database via `database.py`
   - This is a classic **controller → service → persistence** flow.

7. **UI structure**
   - The `templates/` directory contains the server-rendered pages for each major task:
     - authentication: `login.html`
     - admin management: `admin.html`, `add_officer.html`, `remove_officer.html`, `view_officers.html`, `view_firs.html`, `close_fir.html`
     - FIR detail views: `fir_details.html`, `search_fir.html`, `update_fir.html`
     - person/profile views: `complainant_details.html`, `profile.html`
     - officer workflow: `officer.html`, `new_fir.html`
   - These pages are the presentation boundary; they receive Jinja2 data from Flask routes.

8. **Static assets**
   - `static/css/style.css` is the primary stylesheet.
   - There are JavaScript files in `static/js_unused/`, which indicates UI scripts were planned or prototyped but are not part of the active frontend path.
   - The repo currently looks more like a template-driven app with styling support than a fully interactive frontend.

9. **Role-based workflow split**
   - The architecture is split around two operational personas:
     - **Admin**: manages officers and the FIR lifecycle at a supervisory level.
     - **Officer**: handles operational case work and profile-related views.
   - This split is reflected both in routing and in template naming, so it should be shown as a major branch in any diagram.

10. **External dependencies and runtime**
   - The project depends on Flask, Flask-Session, and Werkzeug.
   - Flask-Session matters because session state is part of the app’s authorization model.
   - Werkzeug matters because password hashing is part of the security boundary.
   - No external services are visible in the repo; the system currently appears self-contained around a local database.

11. **Current implementation maturity**
   - The repository is structurally complete but partially implemented:
     - Flask routes and templates exist
     - backend function signatures exist
     - database schema is planned but not fully wired
   - For architecture purposes, the most important thing is that **`app.py` orchestrates, `backend.py` owns business rules, and `database.py` owns persistence**.

12. **How to draw the diagram**
   - Show four main blocks:
     - Browser/UI templates
     - Flask app/controller (`app.py`)
     - Business/service layer (`backend.py`)
     - Database layer (`database.py` + SQLite files)
   - Add cross-cutting concerns:
     - session/auth state
     - role checks
     - password hashing
   - Then branch the domain into admin workflows and officer workflows, both feeding into the same FIR/officer/complainant data store.

Main entry points: [`backend.py`](https://github.com/rockeyyabraham/fir-system/blob/master/backend.py) (Backend service), [`app.py`](https://github.com/rockeyyabraham/fir-system/blob/master/app.py) (Flask app), [`fir.db`](https://github.com/rockeyyabraham/fir-system/blob/master/fir.db) (SQLite data), [`static/css/style.css`](https://github.com/rockeyyabraham/fir-system/blob/master/static/css/style.css) (Stylesheet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_templates_login["Login page<br/>Jinja template<br/>[login.html]"]
  node_templates_admin["Admin pages<br/>Jinja templates<br/>[admin.html]"]
  node_templates_officer["Officer pages<br/>Jinja templates<br/>[officer.html]"]
  node_templates_fir["FIR pages<br/>Jinja templates<br/>[view_firs.html]"]
  node_templates_people["Person pages<br/>Jinja templates<br/>[profile.html]"]
  node_static_css["Stylesheet<br/>CSS<br/>[style.css]"]
end

subgraph group_application["Flask App"]
  node_app_py["Flask app<br/>controller<br/>[app.py]"]
  node_auth_boundary(("Auth state<br/>session/auth"))
  node_admin_workflows["Admin flow<br/>route group"]
  node_officer_workflows["Officer flow<br/>route group"]
end

subgraph group_domain["Domain Logic"]
  node_backend_py["Backend service<br/>service layer<br/>[backend.py]"]
  node_officer_rules{{"Officer rules<br/>domain logic"}}
  node_fir_rules{{"FIR rules<br/>domain logic"}}
  node_complainant_rules{{"Complainant rules<br/>domain logic"}}
end

subgraph group_data["Data Layer"]
  node_database_py["DB boundary<br/>connection layer<br/>[database.py]"]
  node_sqlite_store[("SQLite data<br/>local persistence<br/>[fir.db]")]
  node_schema_sql["Schema SQL<br/>DDL script<br/>[new1.sql]"]
end

node_templates_login -->|"submit login"| node_app_py
node_templates_admin -->|"admin actions"| node_app_py
node_templates_officer -->|"officer actions"| node_app_py
node_templates_fir -->|"view/update FIR"| node_app_py
node_templates_people -->|"profile views"| node_app_py
node_static_css -.->|"style"| node_templates_login
node_static_css -.->|"style"| node_templates_admin
node_static_css -.->|"style"| node_templates_officer
node_app_py -->|"session auth"| node_auth_boundary
node_auth_boundary -->|"admin role"| node_admin_workflows
node_auth_boundary -->|"officer role"| node_officer_workflows
node_app_py -->|"delegate work"| node_backend_py
node_admin_workflows -->|"manage officers/FIRs"| node_backend_py
node_officer_workflows -->|"case operations"| node_backend_py
node_backend_py -->|"validate officers"| node_officer_rules
node_backend_py -->|"FIR lifecycle"| node_fir_rules
node_backend_py -->|"complainant links"| node_complainant_rules
node_backend_py -->|"persist/read"| node_database_py
node_database_py -->|"SQLite files"| node_sqlite_store
node_schema_sql -.->|"define schema"| node_sqlite_store
node_fir_rules -->|"fir data"| node_sqlite_store
node_officer_rules -->|"officer data"| node_sqlite_store
node_complainant_rules -->|"complainant data"| node_sqlite_store

click node_templates_login "https://github.com/rockeyyabraham/fir-system/blob/master/templates/login.html"
click node_templates_admin "https://github.com/rockeyyabraham/fir-system/blob/master/templates/admin.html"
click node_templates_officer "https://github.com/rockeyyabraham/fir-system/blob/master/templates/officer.html"
click node_templates_fir "https://github.com/rockeyyabraham/fir-system/blob/master/templates/view_firs.html"
click node_templates_people "https://github.com/rockeyyabraham/fir-system/blob/master/templates/profile.html"
click node_static_css "https://github.com/rockeyyabraham/fir-system/blob/master/static/css/style.css"
click node_app_py "https://github.com/rockeyyabraham/fir-system/blob/master/app.py"
click node_backend_py "https://github.com/rockeyyabraham/fir-system/blob/master/backend.py"
click node_database_py "https://github.com/rockeyyabraham/fir-system/blob/master/database.py"
click node_sqlite_store "https://github.com/rockeyyabraham/fir-system/blob/master/fir.db"
click node_schema_sql "https://github.com/rockeyyabraham/fir-system/blob/master/new1.sql"

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_templates_login,node_templates_admin,node_templates_officer,node_templates_fir,node_templates_people,node_static_css toneBlue
class node_app_py,node_auth_boundary,node_admin_workflows,node_officer_workflows toneAmber
class node_backend_py,node_officer_rules,node_fir_rules,node_complainant_rules toneMint
class node_database_py,node_sqlite_store,node_schema_sql toneRose
```

## Components

### Presentation

Server-rendered pages and static assets

- [Login page](https://github.com/rockeyyabraham/fir-system/blob/master/templates/login.html): Jinja template · Authentication screen · `templates/login.html`
- [Admin pages](https://github.com/rockeyyabraham/fir-system/blob/master/templates/admin.html): Jinja templates · Admin dashboard and management views · `templates/admin.html`
- [Officer pages](https://github.com/rockeyyabraham/fir-system/blob/master/templates/officer.html): Jinja templates · Officer dashboard and operational views · `templates/officer.html`
- [FIR pages](https://github.com/rockeyyabraham/fir-system/blob/master/templates/view_firs.html): Jinja templates · FIR listing, search, details, update, close · `templates/view_firs.html`
- [Person pages](https://github.com/rockeyyabraham/fir-system/blob/master/templates/profile.html): Jinja templates · Officer and complainant profile views · `templates/profile.html`
- [Stylesheet](https://github.com/rockeyyabraham/fir-system/blob/master/static/css/style.css): CSS · Primary UI styling · `static/css/style.css`

### Flask App

HTTP routes, session state, and role-aware orchestration

- [Flask app](https://github.com/rockeyyabraham/fir-system/blob/master/app.py): controller · Routes, sessions, and workflow coordination · `app.py`
- **Auth state**: session/auth · Composite login and role-based access control
- **Admin flow**: route group · Officer administration and FIR supervision
- **Officer flow**: route group · Operational FIR handling and profile views

### Domain Logic

Business rules for FIR and officer operations

- [Backend service](https://github.com/rockeyyabraham/fir-system/blob/master/backend.py): service layer · Business rules between routes and persistence · `backend.py`
- **Officer rules**: domain logic · Validate officers, roles, and station context
- **FIR rules**: domain logic · Create, read, update, and close FIRs
- **Complainant rules**: domain logic · Create complainants and link them to FIRs

### Data Layer

Database boundary and local persistence artifacts

- [DB boundary](https://github.com/rockeyyabraham/fir-system/blob/master/database.py): connection layer · Database configuration and access boundary · `database.py`
- [SQLite data](https://github.com/rockeyyabraham/fir-system/blob/master/fir.db): local persistence · Repository database files and schema · `fir.db`
- [Schema SQL](https://github.com/rockeyyabraham/fir-system/blob/master/new1.sql): DDL script · Planned schema for officers, FIRs, and complainants · `new1.sql`

## Connections

- Login page → Flask app: submit login · User submits credentials through Flask routes
- Admin pages → Flask app: admin actions · Admin forms and navigation hit controller routes
- Officer pages → Flask app: officer actions · Officer workflow pages submit to routes
- FIR pages → Flask app: view/update FIR · FIR pages invoke route handlers
- Person pages → Flask app: profile views · Profile and complainant views are served by routes
- Stylesheet → Login page: style · Shared stylesheet supports rendered pages
- Stylesheet → Admin pages: style · Shared stylesheet supports rendered pages
- Stylesheet → Officer pages: style · Shared stylesheet supports rendered pages
- Flask app → Auth state: session auth · Flask sessions store officer identity, station, and role
- Auth state → Admin flow: admin role · Role checks gate administrative routes
- Auth state → Officer flow: officer role · Role checks gate operational routes
- Flask app → Backend service: delegate work · Routes call business-service functions
- Admin flow → Backend service: manage officers/FIRs · Admin paths use shared backend operations
- Officer flow → Backend service: case operations · Officer paths use shared backend operations
- Backend service → Officer rules: validate officers · Backend owns officer lookup and role logic
- Backend service → FIR rules: FIR lifecycle · Backend owns FIR creation and updates
- Backend service → Complainant rules: complainant links · Backend creates complainants and associations
- Backend service → DB boundary: persist/read · Service layer uses database boundary
- DB boundary → SQLite data: SQLite files · Local database artifacts store application data
- Schema SQL → SQLite data: define schema · Schema file describes the relational structure
- FIR rules → SQLite data: fir data · FIR records are stored in the local database
- Officer rules → SQLite data: officer data · Officer records and station roles are stored in the database
- Complainant rules → SQLite data: complainant data · Complainants and junction records are stored in the database
