# asistente-informatica-enec/sgp architecture

> Architecture diagram of the GitHub repository asistente-informatica-enec/sgp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asistente-informatica-enec/sgp
- Repository: https://github.com/asistente-informatica-enec/sgp

## Overview

#### Purpose and Runtime

This is a Laravel/PHP asset-management platform built on Orchid’s server-rendered admin UI. It manages institutional assets, civil servants, positions, responsibility cards, assignments/removals, condition tracking, and reports. The README is Laravel boilerplate; the domain is defined by the application tree.

HTTP boots through `public/index.php` and Laravel bootstrap in `bootstrap/app.php`. The primary authenticated application surface is Orchid, configured through `app/Orchid/PlatformProvider.php` and routed in `routes/platform.php`.

#### Core Domain Persistence

Eloquent models represent the business graph: assets, people, organizational positions, custody/responsibility documents, assignment history, removals, and audit records.

- `app/Models/Asset.php`
- `app/Models/CivilServant.php`
- `app/Models/ResponsabilityCard.php`
- `app/Models/Assignment.php`
- `app/Models/AssetRemoval.php`
- `app/Models/ActivityLog.php`

The relational schema is versioned under `database/migrations/`, notably `2026_03_10_193952_create_assets_table.php`, `2026_03_10_193952_create_responsability_cards_table.php`, and `2026_03_10_193953_create_assignments_table.php`. Later migrations enforce responsibility-card and globally unique assignment-code constraints.

#### Orchid Application Boundary

Orchid Screens are the application controllers/use-case layer: they query models, render layouts, and process form actions. Layouts define the actual administrative UI composition, keeping CRUD workflow logic screen-centered rather than in conventional HTTP controllers.

Representative entry points:
- `app/Orchid/Screens/Asset/AssetListScreen.php`
- `app/Orchid/Screens/Asset/AssetEditScreen.php`
- `app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php`
- `app/Orchid/Screens/BadConditionCard/BadConditionCardEditScreen.php`
- `app/Orchid/Screens/Report/ReportBuilderScreen.php`

Generic `app/Http/Controllers/Controller.php` is present, but the tree indicates Orchid is the material UI/control-plane boundary.

#### Asset Lifecycle and Custody Flows

Assets are created, edited, listed, and reviewed through Asset screens/layouts. Asset history is explicitly represented in the UI, likely drawing from assignments/removals/activity records.

- `app/Orchid/Layouts/Asset/AssetEditLayout.php`
- `app/Orchid/Layouts/Asset/AssetHistoryLayout.php`
- `app/Orchid/Layouts/Asset/AssetSelection.php`

Responsibility-card workflows select multiple assets through listener-driven layouts, then persist a card and associated assignments. Bad-condition cards implement a parallel flow for assets discharged due to condition, including staged/batch UI partials and a dedicated selector script.

- `app/Orchid/Layouts/ResponsabilityCard/AssetSelectionListener.php`
- `app/Orchid/Layouts/BadConditionCard/AssetSelectionListener.php`
- `resources/views/orchid/batch-discharge-stepper.blade.php`
- `public/js/asset-batch-selector.js`

#### Personnel, Access, and Audit

Civil servants and positions provide the personnel/organization side of asset custody. Kardex screens expose an employee-centric history of assets and bad-condition activity.

- `app/Orchid/Screens/CivilServant/CivilServantKardexScreen.php`
- `app/Orchid/Layouts/CivilServant/KardexAssetsListLayout.php`
- `app/Orchid/Layouts/CivilServant/KardexBadConditionLayout.php`
- `app/Orchid/Screens/Position/PositionEditScreen.php`

User, role, and permission administration use Orchid’s role system. `EnsurePasswordChanged` is an application-specific security gate, and the users schema includes a mandatory-password-change field.

- `app/Http/Middleware/EnsurePasswordChanged.php`
- `app/Orchid/Screens/Role/RoleEditScreen.php`
- `app/Orchid/Screens/User/UserProfileScreen.php`

#### Imports, Exports, and Reports

Spreadsheet imports ingest assets and civil-servant records; corresponding templates guide source data. Report generation has a generic report export plus domain exports for assets, personnel, and responsibility cards, backed by PDF Blade templates.

- `app/Imports/AssetImport.php`
- `app/Imports/CivilServantImport.php`
- `app/Exports/GenericReportExport.php`
- `app/Exports/ResponsabilityCardExport.php`
- `resources/views/pdf/dynamic_report.blade.php`

#### Infrastructure and External Dependencies

Laravel supplies routing, authentication, Eloquent persistence, queues, caching, sessions, filesystem storage, mail, and logging via `config/`. Orchid is the principal external application framework. Database, queue, cache, filesystem, and service providers are environment-configured rather than fixed in the repository.

- `config/database.php`
- `config/queue.php`
- `config/filesystems.php`
- `config/platform.php`

Vite compiles the limited frontend assets (`resources/js/app.js`, `resources/css/app.css`); server-rendered Orchid/Blade remains the dominant presentation model.

Main entry points: [`app/Models/Asset.php`](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Models/Asset.php) (Asset domain models), [`app/Http/Middleware/EnsurePasswordChanged.php`](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Http/Middleware/EnsurePasswordChanged.php) (Password-change gate), [`app/Orchid/Screens/Asset/AssetEditScreen.php`](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/Asset/AssetEditScreen.php) (Asset screens), [`app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php`](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php) (Custody card screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Laravel Runtime"]
  node_http_entry(("HTTP entry<br/>PHP entry point<br/>[index.php]"))
  node_laravel_bootstrap["Laravel bootstrap<br/>application bootstrap<br/>[app.php]"]
  node_password_gate["Password-change gate<br/>middleware"]
end

subgraph group_orchid["Orchid Admin"]
  node_platform_provider["Platform provider<br/>Orchid provider"]
  node_platform_routes["Admin routes<br/>Orchid routes<br/>[platform.php]"]
  node_asset_screens["Asset screens<br/>Orchid use cases"]
  node_asset_layouts["Asset layouts<br/>Orchid UI layouts"]
  node_custody_screens["Custody card screens<br/>Orchid use cases"]
  node_custody_selector["Custody asset selector<br/>listener layout"]
  node_condition_screens["Bad-condition screens<br/>Orchid use cases"]
  node_condition_selector["Batch discharge selector<br/>listener and client UI"]
  node_personnel_kardex["Personnel and kardex<br/>Orchid use cases"]
  node_access_admin["Users and roles<br/>Orchid access admin<br/>[RoleEditScreen.php]"]
end

subgraph group_domain["Asset Domain"]
  node_domain_models[("Asset domain models<br/>Eloquent model graph<br/>[Asset.php]")]
  node_relational_schema[("Relational schema<br/>Laravel migrations")]
end

subgraph group_dataflows["Data Exchange"]
  node_spreadsheet_imports["Spreadsheet imports<br/>import pipeline<br/>[AssetImport.php]"]
  node_reports_exports["Reports and exports<br/>export pipeline"]
  node_pdf_templates["PDF report template<br/>Blade template"]
end

node_http_entry -->|"boots"| node_laravel_bootstrap
node_laravel_bootstrap -->|"loads providers"| node_platform_provider
node_platform_provider -->|"registers"| node_platform_routes
node_platform_routes -->|"authenticated access"| node_password_gate
node_password_gate -->|"permits"| node_asset_screens
node_password_gate -->|"permits"| node_custody_screens
node_password_gate -->|"permits"| node_condition_screens
node_password_gate -->|"permits"| node_personnel_kardex
node_asset_screens -->|"renders"| node_asset_layouts
node_asset_screens -->|"queries and updates"| node_domain_models
node_custody_screens -->|"selects assets"| node_custody_selector
node_custody_screens -->|"persists cards and assignments"| node_domain_models
node_condition_screens -->|"selects batch"| node_condition_selector
node_condition_screens -->|"records removals"| node_domain_models
node_personnel_kardex -->|"reads custody history"| node_domain_models
node_access_admin -->|"admin surface"| node_platform_routes
node_domain_models -->|"persists through"| node_relational_schema
node_spreadsheet_imports -->|"ingests records"| node_domain_models
node_reports_exports -->|"reads report data"| node_domain_models
node_reports_exports -->|"renders PDF"| node_pdf_templates

click node_http_entry "https://github.com/asistente-informatica-enec/sgp/blob/main/public/index.php"
click node_laravel_bootstrap "https://github.com/asistente-informatica-enec/sgp/blob/main/bootstrap/app.php"
click node_platform_provider "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/PlatformProvider.php"
click node_platform_routes "https://github.com/asistente-informatica-enec/sgp/blob/main/routes/platform.php"
click node_password_gate "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Http/Middleware/EnsurePasswordChanged.php"
click node_asset_screens "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/Asset/AssetEditScreen.php"
click node_asset_layouts "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/Asset/AssetHistoryLayout.php"
click node_custody_screens "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php"
click node_custody_selector "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/ResponsabilityCard/AssetSelectionListener.php"
click node_condition_screens "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/BadConditionCard/BadConditionCardEditScreen.php"
click node_condition_selector "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/BadConditionCard/AssetSelectionListener.php"
click node_domain_models "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Models/Asset.php"
click node_relational_schema "https://github.com/asistente-informatica-enec/sgp/blob/main/database/migrations/2026_03_10_193952_create_assets_table.php"
click node_personnel_kardex "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/CivilServant/CivilServantKardexScreen.php"
click node_access_admin "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/Role/RoleEditScreen.php"
click node_spreadsheet_imports "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Imports/AssetImport.php"
click node_reports_exports "https://github.com/asistente-informatica-enec/sgp/blob/main/app/Exports/GenericReportExport.php"
click node_pdf_templates "https://github.com/asistente-informatica-enec/sgp/blob/main/resources/views/pdf/dynamic_report.blade.php"

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_http_entry,node_laravel_bootstrap,node_password_gate toneBlue
class node_platform_provider,node_platform_routes,node_asset_screens,node_asset_layouts,node_custody_screens,node_custody_selector,node_condition_screens,node_condition_selector,node_personnel_kardex,node_access_admin toneAmber
class node_domain_models,node_relational_schema toneMint
class node_spreadsheet_imports,node_reports_exports,node_pdf_templates toneRose
```

## Components

### Laravel Runtime

- [HTTP entry](https://github.com/asistente-informatica-enec/sgp/blob/main/public/index.php): PHP entry point · `public/index.php`
- [Laravel bootstrap](https://github.com/asistente-informatica-enec/sgp/blob/main/bootstrap/app.php): application bootstrap · `bootstrap/app.php`
- [Password-change gate](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Http/Middleware/EnsurePasswordChanged.php): middleware · Blocks users required to change their password. · `app/Http/Middleware/EnsurePasswordChanged.php`

### Orchid Admin

- [Platform provider](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/PlatformProvider.php): Orchid provider · `app/Orchid/PlatformProvider.php`
- [Admin routes](https://github.com/asistente-informatica-enec/sgp/blob/main/routes/platform.php): Orchid routes · `routes/platform.php`
- [Asset screens](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/Asset/AssetEditScreen.php): Orchid use cases · Asset CRUD and history workflows. · `app/Orchid/Screens/Asset/AssetEditScreen.php`
- [Asset layouts](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/Asset/AssetHistoryLayout.php): Orchid UI layouts · Forms, history, and asset selection UI. · `app/Orchid/Layouts/Asset/AssetHistoryLayout.php`
- [Custody card screens](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php): Orchid use cases · Creates responsibility cards and assignments. · `app/Orchid/Screens/ResponsabilityCard/ResponsabilityCardEditScreen.php`
- [Custody asset selector](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/ResponsabilityCard/AssetSelectionListener.php): listener layout · `app/Orchid/Layouts/ResponsabilityCard/AssetSelectionListener.php`
- [Bad-condition screens](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/BadConditionCard/BadConditionCardEditScreen.php): Orchid use cases · Discharges assets due to condition. · `app/Orchid/Screens/BadConditionCard/BadConditionCardEditScreen.php`
- [Batch discharge selector](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Layouts/BadConditionCard/AssetSelectionListener.php): listener and client UI · Supports staged selection for condition discharges. · `app/Orchid/Layouts/BadConditionCard/AssetSelectionListener.php`
- [Personnel and kardex](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/CivilServant/CivilServantKardexScreen.php): Orchid use cases · Manages positions and employee asset history. · `app/Orchid/Screens/CivilServant/CivilServantKardexScreen.php`
- [Users and roles](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Orchid/Screens/Role/RoleEditScreen.php): Orchid access admin · Orchid role, permission, and profile administration. · `app/Orchid/Screens/Role/RoleEditScreen.php`

### Asset Domain

- [Asset domain models](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Models/Asset.php): Eloquent model graph · Assets, people, cards, assignments, removals, and activity logs. · `app/Models/Asset.php`
- [Relational schema](https://github.com/asistente-informatica-enec/sgp/blob/main/database/migrations/2026_03_10_193952_create_assets_table.php): Laravel migrations · Defines asset, responsibility-card, and assignment constraints. · `database/migrations/2026_03_10_193952_create_assets_table.php`

### Data Exchange

- [Spreadsheet imports](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Imports/AssetImport.php): import pipeline · Ingests asset and civil-servant records. · `app/Imports/AssetImport.php`
- [Reports and exports](https://github.com/asistente-informatica-enec/sgp/blob/main/app/Exports/GenericReportExport.php): export pipeline · Generates generic and domain report exports. · `app/Exports/GenericReportExport.php`
- [PDF report template](https://github.com/asistente-informatica-enec/sgp/blob/main/resources/views/pdf/dynamic_report.blade.php): Blade template · `resources/views/pdf/dynamic_report.blade.php`

## Connections

- HTTP entry → Laravel bootstrap: boots
- Laravel bootstrap → Platform provider: loads providers
- Platform provider → Admin routes: registers
- Admin routes → Password-change gate: authenticated access
- Password-change gate → Asset screens: permits
- Password-change gate → Custody card screens: permits
- Password-change gate → Bad-condition screens: permits
- Password-change gate → Personnel and kardex: permits
- Asset screens → Asset layouts: renders
- Asset screens → Asset domain models: queries and updates
- Custody card screens → Custody asset selector: selects assets
- Custody card screens → Asset domain models: persists cards and assignments
- Bad-condition screens → Batch discharge selector: selects batch
- Bad-condition screens → Asset domain models: records removals
- Personnel and kardex → Asset domain models: reads custody history
- Users and roles → Admin routes: admin surface
- Asset domain models → Relational schema: persists through
- Spreadsheet imports → Asset domain models: ingests records
- Reports and exports → Asset domain models: reads report data
- Reports and exports → PDF report template: renders PDF
