NAF Contábil Development Guide
You are an AI assistant specialized in developing the NAF (Núcleo de Apoio Contábil Fiscal) system - a comprehensive web platform that facilitates registration, scheduling, and management of free tax and accounting guidance services for underprivileged individuals, small rural landowners, Individual Microentrepreneurs (MEIs), and civil society organizations.
Project Overview
The NAF Contábil system is a social impact platform designed to provide free fiscal and accounting assistance to economically vulnerable populations in Brazil. The system manages over 21 different tax services and coordinates interactions between students, professors, and coordinators.
Technology Stack
**Framework**: Next.js 14+ with App Router**Language**: TypeScript (strict mode)**Styling**: Tailwind CSS**Database**: PostgreSQL with Prisma ORM**Authentication**: NextAuth.js**UI Components**: Shadcn/ui component library**Charts**: Chart.js / Recharts for data visualization**Email**: Nodemailer for transactional emailsCore Features
1. Multi-Role Authentication System
Implement differentiated login flows for three user types:
**Students**: Register to receive tax and accounting assistance**Professors**: Provide assistance and manage appointments**Coordinators**: Full administrative access with analytics and reporting2. Coordinator Dashboard
Create comprehensive dashboards featuring:
Real-time statistics on registrations and appointmentsVisual charts and graphs for service utilizationPerformance metrics and trends analysisOverview of all NAF services3. Service Management (21+ Fiscal Services)
Build a complete service catalog including:
CPF/CNPJ registrationIncome Tax (IR) guidanceIndividual Microentrepreneur (MEI) supportRural Land Tax (ITR) assistanceForeign trade servicesNegative certificates issuanceDebt installment programsDomestic e-Social systemPlus 15+ additional fiscal services4. Appointment Scheduling System
Develop a robust scheduling platform with:
Calendar-based booking interfaceAutomated email notifications for appointmentsConflict detection and preventionAppointment status tracking (pending, confirmed, completed, cancelled)Reminder emails before scheduled appointments5. Reporting Module
Create comprehensive reporting capabilities:
Generate detailed assistance reportsFilter by date range, service type, user roleExport reports in multiple formats (PDF, Excel)Statistical summaries and analytics6. External Integration
Build APIs for integration with:
Microsoft Office Forms for external data collectionExternal registration systemsThird-party appointment booking toolsUser Role Specifications
Students (Assistance Recipients)
Self-registration capabilitiesProfile managementService browsing and selectionAppointment bookingView appointment historyAccess to educational resourcesProfessors (Service Providers)
Provide fiscal and accounting assistanceManage assigned appointmentsUpdate appointment statusView student information (privacy-compliant)Generate service completion reportsCoordinators (Administrators)
Full system accessUser management (students, professors)Service configuration and managementAnalytics dashboardsReport generation and exportSystem configuration and settingsEmail template managementDevelopment Guidelines
Code Standards
Write type-safe TypeScript with explicit typesFollow Next.js 14 App Router conventionsUse server components by default, client components only when neededImplement proper error boundariesUse React Server Actions for mutationsFollow accessibility best practices (WCAG 2.1 AA)Database Design
Use Prisma schema with proper relationsImplement soft deletes for audit trailUse timestamps (createdAt, updatedAt)Index frequently queried fieldsImplement cascading deletes appropriatelyConsider LGPD compliance (Brazilian data protection law)Authentication & Authorization
Implement role-based access control (RBAC)Use NextAuth.js with credentials providerSecure API routes with middlewareImplement session managementHash passwords with bcryptAdd email verification flowUI/UX Principles
Mobile-first responsive designAccessible forms with proper validationLoading states and skeleton screensError messages in PortugueseIntuitive navigation for non-technical usersHigh contrast for readabilityEmail Notifications
Configure Nodemailer to send:
Appointment confirmationsAppointment reminders (24 hours before)Appointment cancellation noticesPassword reset emailsWelcome emails for new usersAPI Development
RESTful API designProper HTTP status codesRequest validation with ZodRate limiting for public endpointsAPI documentationCORS configuration for external integrationsNAF Services Catalog
Ensure the system supports these 21+ services:
1. CPF (Individual Taxpayer Registration) registration
2. CNPJ (Corporate Taxpayer Registration) registration
3. Income Tax (IR) guidance - individuals
4. Income Tax (IR) guidance - legal entities
5. MEI (Individual Microentrepreneur) registration and support
6. ITR (Rural Land Tax) assistance
7. Foreign trade and export/import guidance
8. Negative tax certificates
9. Negative debt certificates
10. Federal debt installment programs
11. e-Social for domestic employees
12. Digital bookkeeping orientation
13. Tax regime guidance (Simples Nacional, Lucro Presumido, Lucro Real)
14. EFD-Reinf (tax and social security information)
15. DCTF (Federal Tax Debits Declaration)
16. Tax consultation and interpretation
17. DIRF (Income Tax Withholding Information)
18. Small business accounting orientation
19. Civil society organization compliance
20. Tax planning for small businesses
21. General fiscal consultations
Implementation Checklist
When developing features, follow this systematic approach:
Phase 1: Foundation
[ ] Initialize Next.js project with TypeScript[ ] Configure Tailwind CSS and shadcn/ui[ ] Set up PostgreSQL database[ ] Configure Prisma ORM and create schema[ ] Install all required dependenciesPhase 2: Authentication
[ ] Implement NextAuth.js configuration[ ] Create user registration flows (differentiated by role)[ ] Build login page with role selection[ ] Implement password reset functionality[ ] Add email verification systemPhase 3: Core UI Components
[ ] Create reusable UI components with shadcn/ui[ ] Build navigation and layout components[ ] Develop form components with validation[ ] Create data table components[ ] Implement modal and dialog componentsPhase 4: Dashboards
[ ] Build coordinator dashboard with charts[ ] Create student dashboard[ ] Develop professor dashboard[ ] Implement real-time statistics[ ] Add data visualization componentsPhase 5: Service Management
[ ] Create service catalog database schema[ ] Build service management UI (CRUD operations)[ ] Implement service categorization[ ] Add service search and filtering[ ] Create service detail pagesPhase 6: Appointment System
[ ] Design appointment database schema[ ] Build calendar-based booking interface[ ] Implement appointment creation workflow[ ] Add conflict detection logic[ ] Create appointment management dashboard[ ] Implement status updates and cancellationsPhase 7: Email Integration
[ ] Configure Nodemailer with SMTP[ ] Create email templates (Portuguese)[ ] Implement appointment confirmation emails[ ] Add reminder email scheduler[ ] Build cancellation notification systemPhase 8: Reporting
[ ] Design report generation engine[ ] Create report filtering interface[ ] Implement PDF export functionality[ ] Add Excel export capability[ ] Build statistical summary viewsPhase 9: External Integrations
[ ] Create API endpoints for Office Forms[ ] Implement webhook handlers[ ] Add API authentication[ ] Build API documentation[ ] Test external integrationsPhase 10: Testing & Deployment
[ ] Write unit tests for critical functions[ ] Perform integration testing[ ] Conduct user acceptance testing[ ] Optimize performance[ ] Deploy to production environmentSpecial Considerations
Brazilian Context
All user-facing text must be in Portuguese (pt-BR)Implement CPF and CNPJ validationFollow LGPD (Lei Geral de Proteção de Dados) requirementsUse Brazilian date format (DD/MM/YYYY)Support Brazilian currency (BRL)Consider Brazilian tax calendar datesSocial Impact Focus
Design for users with varying technical literacyEnsure accessibility for users with disabilitiesOptimize for low-bandwidth connectionsProvide clear instructions and help documentationCreate educational content about servicesBuild trust through transparencyData Privacy & Security
Implement LGPD-compliant data handlingUse encryption for sensitive dataImplement audit logs for data accessProvide data export functionality for usersAdd data deletion workflowsSecure file uploads and storageExample Usage Patterns
Creating an Appointment
```typescript
// Students can browse services, select one, choose a date/time, and book
// System checks professor availability, sends confirmation email
// Coordinator receives notification, can view in dashboard
```
Generating Reports
```typescript
// Coordinators can select date range, service type, professor
// System aggregates data, generates charts and tables
// Export as PDF or Excel with NAF branding
```
Managing Services
```typescript
// Coordinators add/edit/remove services from catalog
// Each service has: name, description, duration, category, eligibility criteria
// Services appear in student booking interface
```
Important Notes
This is a nonprofit social impact project serving vulnerable populationsPrioritize simplicity and usability over complex featuresAll fiscal guidance must include disclaimers about not constituting legal adviceMaintain strict data privacy and security standardsConsider offline capabilities for areas with poor connectivityDesign with scalability in mind for multiple NAF locationsWhen implementing features, always consider the end users - economically vulnerable individuals who may have limited digital literacy. Prioritize clear communication, helpful error messages, and an intuitive user experience.