How lbenitesanchez/gestion-jurados-proyecto-empresarial_copia works
1. Overall shape
- This is a React + TypeScript frontend built with Vite, plus a small Node/Netlify API layer for local development and deployment flexibility.
- The application domain is jury management for academic projects: ingest professor preferences, consolidate them, form juries, validate assignments, and generate outputs such as reports and emails.
2. Two-stage product model
- The UI is split into Stage 1 and Stage 2, which appear to represent the main workflow boundaries.
- Stage 1 focuses on intake, normalization, and analysis of raw data from Google Forms/Sheets.
- Stage 2 focuses on operational management: professor profiles, work management, jury assignment, reporting, and settings.
3. Presentation layer
- src/App.tsx and src/main.tsx bootstrap the app.
- src/components/layout contains the application shell and navigation (AppShell, Sidebar), which likely frame all dashboards.
- src/components/common provides reusable UI building blocks such as metric cards, section cards, and status badges.
4. Stage 1 subsystem: data intake and consolidation
- src/components/stage1 contains the interfaces for the ingestion and analysis flow:
- FileUploader for importing files,
- FiltersBar for narrowing datasets,
- SummaryCards and ProfessorWorkMatrix for analytics,
- WorkTable and WorkDetailPanel for work-level inspection,
- Stage1Dashboard as the container view.
- This stage is where raw response data is turned into structured operational information.
5. Stage 2 subsystem: assignment operations
- src/components/stage2 contains the downstream management workflow:
- JuryAssignmentPanel for forming juries,
- ProfessorProfiles and WorkManagement for entity administration,
- ReportsView for output generation,
- SettingsView for operational controls,
- HomeDashboard and Stage2Dashboard as top-level views.
- This stage is where validated assignments are edited, locked, reviewed, and exported.
6. Domain and processing services
- src/services is the main application/service boundary and likely contains most non-UI logic.
- The services split naturally into:
- domain logic: juryAggregationService, juryAssignmentService, rulesEngineService,
- data ingestion/parsing: fileParserService,
- integration adapters: googleSheetsService, openaiAgentService, emailService,
- delivery/output: exportService,
- state/governance: storageService, auditLogService.
- This suggests a clean separation between UI, business rules, and external integrations.
7. External system integrations
- Google Sheets is the data source for Google Forms responses and work lists.
- OpenAI is used for assisted jury formation or recommendation support.
- Email/SMTP is used for controlled distribution of notifications, with test-vs-production safeguards.
- Export/report generation is part of the operational output pipeline.
8. Data model and shared types
- src/types/domain.ts defines the core domain entities used across UI and services.
- src/utils/text.ts likely provides normalization or text-cleaning helpers used during parsing and matching.
- src/data/mockData.ts supports local development/demo states when live integrations are unavailable.
9. Runtime and deployment boundaries
- Local development runs the frontend on Vite and an API on Node (server/index.mjs), matching the README ports 5173 and 8787.
- There is also a Netlify Function entry point at netlify/functions/api.mjs, indicating a serverless deployment path for API endpoints.
- netlify.toml and the README indicate the frontend is deployable as static assets, while the API can be hosted either as Netlify Functions or a separate backend.
10. Configuration and secrets
- .env.example shows the system depends on runtime secrets for OpenAI, Google Sheets, and SMTP.
- This means the architecture has a clear split between:
- client-visible UI logic, and
- server-side/integration-sensitive operations that require credentials and controlled sending.
- The README’s warning about not committing credentials indicates those integrations are operationally important to the system.
11. Operational flow
- The likely end-to-end flow is:
- ingest responses from Google Sheets or uploaded files,
- parse and normalize the data,
- compute summaries and professor-work coverage,
- generate or refine jury assignments,
- allow manual correction and locking,
- store/audit changes,
- export reports and optionally email results.
- The architecture is centered on this workflow rather than on generic CRUD.
12. Documentation and support material
- docs/manual-coordinadora.md suggests the repo includes user-facing operational guidance, which is important for a workflow-heavy administrative tool.
- This reinforces that the system is designed for coordinators and staff rather than end students.
13. How to draw the architecture
- A good diagram would show:
- a React frontend with Stage 1 and Stage 2 views,
- a shared service layer for parsing, rules, aggregation, assignment, and integrations,
- external systems: Google Sheets, OpenAI, SMTP/email, and file/export output,
- a Node/Netlify API boundary with local dev and deployable serverless endpoints,
- and an audit/storage layer for traceability and controlled changes.
Main entry points: Stage1Dashboard.tsx Stage 1 · Stage2Dashboard.tsx Stage 2 · AppShell.tsx App Shell · fileParserService.ts Parser
Components 34
Frontend
React/Vite UI for the two-stage workflow
- main · Vite entry that mounts the React app
src/main.tsx - App · Top-level app composition and routing
src/App.tsx - App Shell · Global frame and navigation container
src/components/layout/AppShell.tsx - Sidebar · Primary navigation between workflow stages
src/components/layout/Sidebar.tsx - Common UI · Reusable cards and status elements
src/components/common/MetricCard.tsx
Stage 1
Intake, normalization, and analysis
- Stage 1 · Intake and consolidation dashboard
src/components/stage1/Stage1Dashboard.tsx - File Upload · Imports source files into the workflow
src/components/stage1/FileUploader.tsx - Filters · Narrows the dataset for review
src/components/stage1/FiltersBar.tsx - Summary · High-level intake and coverage metrics
src/components/stage1/SummaryCards.tsx - Matrix · Professor-work coverage matrix
src/components/stage1/ProfessorWorkMatrix.tsx - Work Table · Inspectable list of works and responses
src/components/stage1/WorkTable.tsx - Work Detail · Focused inspection of a selected work
src/components/stage1/WorkDetailPanel.tsx
Stage 2
Operations, assignments, and outputs
- Stage 2 · Operations dashboard for assignments and outputs
src/components/stage2/Stage2Dashboard.tsx - Home · Stage 2 landing dashboard
src/components/stage2/HomeDashboard.tsx - Jury Assign · Forms and adjusts jury compositions
src/components/stage2/JuryAssignmentPanel.tsx - Profiles · Professor profile management
src/components/stage2/ProfessorProfiles.tsx - Work Mgmt · Operational control of works and status
src/components/stage2/WorkManagement.tsx - Reports · Report generation and review
src/components/stage2/ReportsView.tsx - Settings · Operational settings and safeguards
src/components/stage2/SettingsView.tsx
Services
Business rules, integrations, storage, and delivery
- Parser · Normalizes uploaded and sourced input data
src/services/fileParserService.ts - Sheets · Google Sheets data source adapter
src/services/googleSheetsService.ts - Aggregation · Consolidates professor and work data
src/services/juryAggregationService.ts - Rules Engine · Applies assignment and validation rules
src/services/rulesEngineService.ts - Assignment · Builds and refines jury assignments
src/services/juryAssignmentService.ts - OpenAI · Assisted recommendation and generation support
src/services/openaiAgentService.ts - Storage · Persists workflow state and locks
src/services/storageService.ts - Audit Log · Tracks changes for traceability
src/services/auditLogService.ts - Export · Produces reports and downloadable outputs
src/services/exportService.ts - Email · Notification and distribution adapter
src/services/emailService.ts - Node API · Local server entry for API access
server/index.mjs - Netlify API · Deployable function entry point
netlify/functions/api.mjs - Mock Data · Local development fallback dataset
src/data/mockData.ts - Domain Types · Core entities shared across UI and services
src/types/domain.ts - Text Utils · Text cleaning and matching helpers
src/utils/text.ts
Connections 37
- main → App: bootstraps · Mounts the root application
- App → App Shell: wraps · Places the app inside the global shell
- App Shell → Sidebar: navigates · Provides stage navigation
- App Shell → Stage 1: shows · Routes to Stage 1 workflow
- App Shell → Stage 2: shows · Routes to Stage 2 workflow
- App Shell → Common UI: uses · Shares common presentation pieces
- Stage 1 → File Upload: contains · Entry point for intake
- Stage 1 → Filters: contains · Dataset filtering controls
- Stage 1 → Summary: contains · Headline metrics and status
- Stage 1 → Matrix: contains · Coverage analysis view
- Stage 1 → Work Table: contains · Work inspection table
- Stage 1 → Work Detail: contains · Selected work detail panel
- Stage 2 → Home: contains · Stage 2 landing view
- Stage 2 → Jury Assign: contains · Assignment editing workspace
- Stage 2 → Profiles: contains · Professor administration
- Stage 2 → Work Mgmt: contains · Work administration
- Stage 2 → Reports: contains · Report generation view
- Stage 2 → Settings: contains · Operational controls
- File Upload → Parser: parses via · Uploads are normalized into domain data
- Parser → Text Utils: normalizes · Uses text cleanup and matching helpers
- Parser → Domain Types: produces · Outputs structured domain entities
- Sheets → Parser: feeds · Sheets data is parsed into the same model
- Parser → Aggregation: loads · Parsed inputs flow into consolidation
- Aggregation → Rules Engine: evaluates · Applies business constraints and validations
- Rules Engine → Assignment: governs · Validated data drives assignments
- Assignment → OpenAI: augments with · Optional AI-assisted recommendations
- Assignment → Storage: persists · Saves assignments and locks
- Storage → Audit Log: logs · Records state-changing actions
- Assignment → Export: exports · Produces operational outputs
- Export → Email: distributes · Sends results and notifications
- Node API → Sheets: serves · Local backend access to integrations
- Node API → Email: serves · Local backend access to notifications
- Node API → OpenAI: serves · Local backend access to AI integration
- Netlify API → Sheets: serves · Serverless access to integrations
- Netlify API → Email: serves · Serverless access to notifications
- Netlify API → OpenAI: serves · Serverless access to AI integration
- Mock Data → Stage 1: supports · Fallback data for local UI