Plataforma-de-desarrolladores/AGENTS_ARQUITECTURA.md

AGENTS_ARQUITECTURA.md

These rules complement AGENTS.md and are mandatory whenever the task changes project structure, C# architecture, database access, repositories, services, contracts, models, or application transactions.

Project folder rules

Use this base structure:

SIG.Web/
  App_Code/
    Infrastructure/
    Sql/
    Repositories/
    Security/
    Utilities/
    Contracts/
    Models/
    Services/
  Styles/
  Scripts/
  Metronic/
  Site.master
  Site.master.cs
  Login.aspx
  Login.aspx.cs
  Inicio.aspx
  Inicio.aspx.cs
  BundleConfig.cs
  Global.asax
  Global.asax.cs
  Web.config

Rules:

• The active application uses the ASP.NET Web Site runtime-compilation model.
• Shared C# source belongs in the exact special folder App_Code.
• Pages, master pages, controls, handlers, and Global.asax use CodeFile or source compiled from App_Code; do not introduce new CodeBehind dependencies on SIG.Web.dll.
• Keep third-party and external assemblies in bin, but do not build or deploy a project assembly named SIG.Web.dll.
• Do not place database access directly inside .aspx.cs, .ascx.cs, or Site.master.cs.
• Database-related helpers go under App_Code/Sql or a clearly named SQL/data folder.
• Business access goes through Contracts and Services.
• The active Web Site does not use explicit project compilation entries; C# files under App_Code compile automatically at runtime.

---

Contract rules

Contracts belong in /Contracts.

Current minimum contracts:

Contracts/IAuthContract.cs
Contracts/IUserSessionContract.cs
Contracts/IMenuContract.cs
Contracts/IMasterPageContract.cs

Suggested future contracts:

Contracts/IPermissionContract.cs
Contracts/INotificationContract.cs
Contracts/ICatalogSearchContract.cs
Contracts/IAuditContract.cs
Contracts/ICurrentCompanyContract.cs

Rules:

• Pages call contracts, not SQL classes.
• Master page calls contracts, not SQL classes.
• Login calls contracts, not SQL classes.
• Contracts must return models, DTOs, or result objects, not raw DataTable unless migrating legacy code.
• If legacy DataTable is required, isolate it behind a contract and document why.

---

Repository ownership rules

Repository ownership is determined by the data domain and stored-procedure prefix, not by the page or feature that currently consumes the data.

• Procedures named PA_Gral_* belong behind contracts and repositories under Contracts/General and Repositories/General.
• General catalogs such as states, countries, municipalities, neighborhoods, and postal codes must not be placed in a security, registration, sales, or page-specific repository.
• A feature service such as public registration may orchestrate both its feature repository and IGeneralCatalogRepository, but it must not move general catalog access into the feature repository.
• Apply the same ownership rule to future procedure families: PA_Sis_* belongs to security/system infrastructure, PA_Tra_* to procedures, PA_Vta_* to sales, and so on.

Database executor ownership rules

• IDbExecutor, DbExecutor, StoredProcedureCommand, IDbCommand, and direct stored-procedure execution may only be used inside classes under Repositories or repository database infrastructure.
• Services must not reference or receive IDbExecutor, create database commands, execute readers, or call stored procedures directly.
• A service that needs persisted data must depend on a repository contract. The concrete repository receives IDbExecutor and owns parameter configuration and result mapping.
• Keep the DbExecutor implementation under Repositories/Database; do not place it under Services or expose it publicly through AppServices.

---

Service rules

Services belong in /Services.

Current starter services may include:

Services/ContractRegistry.cs
Services/DummyAuthContract.cs
Services/UserSessionContract.cs
Services/DummyMenuContract.cs
Services/MasterPageContract.cs

Rules:

• ContractRegistry may be used as a simple manual dependency resolver for WebForms.
• Do not introduce a complex dependency injection framework unless required.
• Services may depend on SQL helpers/repositories.
• .aspx.cs files should be thin and delegate work to services.
• Keep dummy services separate from SQL-backed services.
• Services own application transactions when one business operation performs one or more repository mutations.
• Use TransactionLogic inside a using block around the repository calls and invoke Commit() only after every required repository result succeeds.
• Pages and repositories must not create, commit, roll back, or dispose application transactions.
• Repositories participate through the ambient TransactionScope; connection strings used for transactional work must not set Enlist=false.
• Select TransactionScopeOption, isolation level, and timeout in the service according to the business operation. Use RequiresNew or Suppress only when that behavior is intentional and documented by the call site.
• Do not include slow external operations such as SMTP or HTTP calls inside a database transaction.

---

Model rules

Models belong in /Models.

Current starter models may include:

Models/AppUser.cs
Models/LoginResult.cs
Models/MenuItemModel.cs
Models/MasterLayoutModel.cs
Models/BreadcrumbItem.cs

Rules:

• Use models to move data between contracts and WebForms pages.
• Do not pass anonymous objects across layers.
• Do not expose SQL connection classes or SqlDataReader from services to pages.
• Keep models simple and serializable when possible.

---

Database and SQL structure rules

All database connection structure must be centralized under App_Code/Sql or an equivalent SQL/data folder.

Current starter SQL structure:

App_Code/Sql/ConnectionNames.cs
App_Code/Sql/IConnectionStringProvider.cs
App_Code/Sql/WebConfigConnectionStringProvider.cs
App_Code/Sql/SqlConnectionFactory.cs
App_Code/Sql/SqlQueryExecutor.cs

Rules:

• Define connection names in one place.
• Read connection strings from Web.config.
• Do not hardcode connection strings in pages, master, controls, or services.
• Do not create SqlConnection directly in .aspx.cs.
• Do not create SqlCommand directly in .aspx.cs.
• Use repositories or SQL executor classes behind contracts.
• All application database reads and writes must use stored procedures; inline SQL in C# is prohibited.
• Access to modules and catalogs is controlled by the menu and page-access layer. Reusable catalog stored procedures must not query Sis_Usuarios, restrict execution by CveRol, or return access-denied messages for module authorization.
• Keep @CveUsuarioEjecuta in catalog procedures for the required signature and auditing when applicable, not to authorize access to the module.
• Do not invent or add authorization, role, user-client association, ownership, or business-prerequisite validations to any stored procedure unless the user explicitly requests that exact validation. The user prefers to add those validations manually.
• Mandatory: read and follow AGENTS_STORED_PROCEDURES.md for naming, output parameters, TRY/CATCH, logging, transactions, and physical deletion.
• Mandatory: read and follow AGENTS_DATA_READER_MAPPING.md for object, list, DataTable, and JArray result mapping.
• Mandatory: read and follow AGENTS_DATABASE_ERROR_LOGGING.md for safe parameter logging and reproducible stored-procedure calls.
• Mandatory: read and follow AGENTS_PAGE_STRUCTURE.md for the Pages/Modulo/ location of all new WebForms pages.
• Mandatory: read and follow AGENTS_WEBFORMS_PARTIAL_POSTBACKS.md for the single master form, ScriptManager ownership, UpdatePanel usage, and partial-postback rules.
• Mandatory: read and follow AGENTS_JAVASCRIPT_INITIALIZATION.md for per-element initialization flags, global event guards, and idempotent control setup after partial postbacks.
• Mandatory: read and follow AGENTS_CATALOG_STRUCTURE.md for catalog titles, breadcrumbs, actions, filters, indicators, grids, quick-create modals, and detail pages.
• Mandatory: read and follow AGENTS_DOCUMENT_STORAGE.md for document folders, client access validation, protected file retrieval, and GIS file naming.
• Keep stored procedure names centralized.
• Repositories must use CommandType.StoredProcedure and parameterized inputs/outputs.
• Never concatenate raw user input into SQL.
• The database default collation and general text columns must use Modern_Spanish_CS_AS.
• Columns named Codigo, beginning with Codigo, or containing a real user login identifier such as NombreUsuario, UsuarioPortal, or Acum_PortalUsuario must use Modern_Spanish_CI_AS.
• AgenteUsuario is browser/device metadata, not a login identifier, and must use the general Modern_Spanish_CS_AS collation.
• Do not use Modern_Spanish_CS_AI.

Recommended Web.config connection string pattern:

<connectionStrings>
  <add name="DefaultConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="SecurityConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="ReportingConnection" connectionString="..." providerName="System.Data.SqlClient" />
</connectionStrings>

---

Base page rules

Normal pages should inherit from a C# base page.

Preferred base class:

App_Code/Infrastructure/ClsPaginaBase.cs

If the starter currently has WebFormsPageBase.cs, either:

• rename it to ClsPaginaBase.cs, or
• keep WebFormsPageBase and update this AGENTS.md/project rules consistently.

Do not keep both base classes doing the same job.

Base page responsibilities:

• Validate authenticated session.
• Expose current user from IUserSessionContract.
• Provide helper methods for messages, redirects, and permissions.
• Avoid database access.
• Avoid page-specific business logic.

---