Technical Architecture Document

Project: Conformo - GDPR Compliance Platform for Italian SMEs
Version: 1.0
Last Updated: 2025-10-16
Status: Active Development

Executive Summary
Current Architecture
Target Architecture
Technology Stack
System Components
Data Architecture
Security Architecture
Deployment Architecture
Integration Points
Scalability & Performance
Future Enhancements

Executive Summary

Conformo is a GDPR compliance platform designed specifically for Italian Small and Medium Enterprises (SMEs). The platform transforms complex GDPR regulations into simple, actionable steps using AI-powered automation.

Key Architectural Principles

Modularity: Separated frontend, backend, and API layers for independent scaling and development
Security-First: JWT-based authentication, encrypted data storage, comprehensive audit logging
Italian-Centric: Full localization with Italian business context integration
Cloud-Native: Serverless architecture on Vercel with managed services
Scalability: Stateless design enabling horizontal scaling

Current Architecture

Architecture Overview

The platform follows a three-tier architecture pattern:

┌─────────────────────────────────────────────────────────────┐
│                      Client Layer                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │   React SPA (Vite)                                    │  │
│  │   - React Router for navigation                       │  │
│  │   - React Hook Form for form management              │  │
│  │   - Context API for state management                 │  │
│  │   - Axios for API communication                      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           ↕ HTTPS/REST
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │   Express.js API Server (Node.js 22)                 │  │
│  │   - RESTful API endpoints                            │  │
│  │   - JWT authentication middleware                    │  │
│  │   - Rate limiting & CORS                             │  │
│  │   - Validation (Joi schemas)                         │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │   Business Services                                   │  │
│  │   - Authentication Services                           │  │
│  │   - Password Service (bcrypt)                        │  │
│  │   - Token Service (JWT)                              │  │
│  │   - Email Service (SendGrid)                         │  │
│  │   - Audit Logger                                     │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           ↕ TCP/SQL
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                              │
│  ┌────────────────────┐  ┌───────────────────────────────┐ │
│  │  PostgreSQL 15     │  │  Redis 7                      │ │
│  │  - User data       │  │  - Session cache              │ │
│  │  - Sessions        │  │  - Rate limit counters        │ │
│  │  - Tokens          │  │                               │ │
│  │  - Audit logs      │  │                               │ │
│  └────────────────────┘  └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Current Deployment Model

Platform: Vercel (Serverless)

Frontend: Static site deployed to Vercel CDN
Backend: Serverless functions (@vercel/node runtime)
Database: Managed PostgreSQL (external provider required)
Cache: Managed Redis (external provider required)

Request Flow

User Request → Vercel CDN
Static Assets → Served from CDN
API Requests → Routed to serverless functions
Authentication → JWT validation middleware
Business Logic → Service layer processing
Data Access → PostgreSQL queries
Response → JSON via REST API

Target Architecture

Planned Enhancements

The target architecture maintains the current three-tier structure while adding:

1. AI Integration Layer (Planned)

┌─────────────────────────────────────────────────────────────┐
│                    AI Services Layer                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │   Compliance Wizard AI                               │  │
│  │   - Natural language processing                      │  │
│  │   - GDPR requirement analysis                        │  │
│  │   - Document generation engine                       │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2. Document Generation Pipeline (Planned)

Privacy policy generator
Data processing agreement templates
GDPR compliance checklists
Cookie policy generator

3. Compliance Dashboard (Planned)

Real-time compliance status
Risk assessment indicators
Action item tracking
Deadline management

4. Data Subject Rights Management (Planned)

Access request handling
Data portability tools
Deletion request workflow
Consent management

Migration Path

Phase 1: Current (Complete)

✅ Core authentication system
✅ Italian localization
✅ Basic user management

Phase 2: Foundation (Next)

AI compliance wizard integration
Privacy policy generator
Compliance dashboard MVP

Phase 3: Expansion (Future)

Data subject rights portal
Advanced analytics
Multi-language support
API for third-party integrations

Technology Stack

Frontend Technologies

Component	Technology	Version	Purpose
Framework	React	18.2.0	UI component library
Build Tool	Vite	4.4.0	Fast build and dev server
Language	TypeScript	5.0.0	Type-safe development
Routing	React Router	7.9.4	Client-side routing
Forms	React Hook Form	7.65.0	Form state management
Validation	Zod	4.1.12	Schema validation
HTTP Client	Axios	1.12.2	API communication

Backend Technologies

Component	Technology	Version	Purpose
Runtime	Node.js	22.x	JavaScript runtime
Framework	Express.js	4.18.0	Web application framework
Language	TypeScript	5.4.0	Type-safe development
Database Client	pg	8.16.3	PostgreSQL driver
Authentication	jsonwebtoken	9.0.2	JWT token handling
Password Hashing	bcrypt	6.0.0	Secure password storage
Validation	Joi	18.0.1	Request validation
Email	SendGrid	8.1.6	Transactional emails
Caching	redis	5.8.3	Session and rate limiting
Rate Limiting	express-rate-limit	8.1.0	API protection

Database & Infrastructure

Component	Technology	Version	Purpose
Database	PostgreSQL	15	Primary data store
Cache	Redis	7	Session cache, rate limits
Hosting	Vercel	-	Serverless deployment
CDN	Vercel CDN	-	Static asset delivery
Email Service	SendGrid	-	Email delivery

Development Tools

Tool	Purpose
tsx	TypeScript execution for development
Docker Compose	Local development environment
Git	Version control
npm	Package management

System Components

Frontend Components

1. Authentication Module

Location: frontend/src/components/auth/

RegisterForm.tsx: Multi-step registration with Italian business fields
LoginForm.tsx: Login with account lockout display
ForgotPasswordForm.tsx: Password reset request
ResetPasswordForm.tsx: Password reset completion
PasswordStrengthMeter.tsx: Real-time password validation
AuthLayout.tsx: Common layout for auth pages
EmailVerificationPage.tsx: Email verification handler
ResetPasswordPage.tsx: Password reset page

2. State Management

Location: frontend/src/hooks/auth/

AuthContext.tsx: Global authentication state using React Context
- User session management
- Login/logout actions
- Token refresh handling
- Authentication status

3. API Client Layer

Location: frontend/src/services/

authApi.ts: Authentication API client
- Axios-based HTTP client
- Automatic token injection
- Error handling
- Request/response interceptors

4. Constants & Configuration

Location: frontend/src/constants/

italianData.ts: Italian-specific data
- 107 Italian provinces
- Business types (S.r.l., S.p.A., etc.)
- Employee count ranges

Backend Components

1. API Layer

Location: backend/api/auth/

RESTful endpoints for authentication:

register.ts - User registration (POST /api/auth/register)
login.ts - User authentication (POST /api/auth/login)
logout.ts - Session termination (POST /api/auth/logout)
refreshToken.ts - Token refresh (POST /api/auth/token/refresh)
verifyEmail.ts - Email verification (POST /api/auth/verify-email)
forgotPassword.ts - Password reset request (POST /api/auth/forgot-password)
resetPassword.ts - Password reset (POST /api/auth/reset-password)
profile.ts - User profile (GET /api/auth/profile)

2. Service Layer

Location: backend/services/auth/

Business logic services:

passwordService.ts: Password operations
- Hashing with bcrypt (12 rounds)
- Strength validation
- Dictionary checking
tokenService.ts: Token management
- JWT generation and verification
- Token rotation
- Session management
emailService.ts: Email operations
- SendGrid integration
- Italian email templates
- Verification and reset emails
authLogger.ts: Audit logging
- Authentication event tracking
- Security monitoring

3. Middleware & Utilities

Location: backend/utils/

authMiddleware.ts: JWT authentication middleware
validation.ts: Joi validation schemas
rateLimiter.ts: Rate limiting configurations

4. Database Layer

Location: backend/db/

connection.ts: PostgreSQL connection pool
schema.sql: Database schema definition

5. Shared Components

Location: shared/

featureFlags.ts: Feature toggle system
utils/: Shared utility functions

Data Architecture

Database Schema

Users Table

Primary entity for user accounts

Column	Type	Purpose
id	UUID	Primary key
email	VARCHAR(255)	Unique user email
password_hash	VARCHAR(255)	Bcrypt hashed password
first_name	VARCHAR(100)	User first name
last_name	VARCHAR(100)	User last name
business_info	JSONB	Italian business context
email_verified	BOOLEAN	Email verification status
failed_login_attempts	INTEGER	Lockout tracking
locked_until	TIMESTAMP	Account lockout time
last_login_at	TIMESTAMP	Last successful login
terms_accepted_at	TIMESTAMP	Terms acceptance timestamp
created_at	TIMESTAMP	Account creation time
updated_at	TIMESTAMP	Last update time

Indexes:

idx_users_email on email (unique)
Business info searchable via JSONB operators

User Sessions Table

JWT refresh token storage

Column	Type	Purpose
id	UUID	Primary key
user_id	UUID	Foreign key to users
refresh_token_hash	VARCHAR(255)	Hashed refresh token
device_info	VARCHAR(255)	User agent string
ip_address	VARCHAR(45)	Request IP address
expires_at	TIMESTAMP	Token expiration
created_at	TIMESTAMP	Session creation
last_used_at	TIMESTAMP	Last token use
revoked	BOOLEAN	Revocation status

Indexes:

idx_user_sessions_user_expires on user_id, expires_at

User Tokens Table

Email verification and password reset tokens

Column	Type	Purpose
id	UUID	Primary key
user_id	UUID	Foreign key to users
token_hash	VARCHAR(255)	Hashed token
token_type	VARCHAR(50)	‘email_verification’ or ‘password_reset’
expires_at	TIMESTAMP	Token expiration
used	BOOLEAN	Token usage status
created_at	TIMESTAMP	Token creation

Indexes:

idx_user_tokens_hash on token_hash
idx_user_tokens_user_type on user_id, token_type

Auth Logs Table

Comprehensive audit trail

Column	Type	Purpose
id	UUID	Primary key
event_type	VARCHAR(50)	Event category
user_id	UUID	User (if applicable)
email_attempted	VARCHAR(255)	Email used in attempt
ip_address	VARCHAR(45)	Request IP
user_agent	TEXT	Browser/device info
success	BOOLEAN	Operation success
metadata	JSONB	Additional context
created_at	TIMESTAMP	Event timestamp

Indexes:

idx_auth_logs_user_time on user_id, created_at
idx_auth_logs_email_time on email_attempted, created_at

Data Flow

User Registration Flow:

Client submits registration form
Backend validates input (Joi schema)
Password hashed with bcrypt
User record created in users table
Verification token created in user_tokens
Verification email sent via SendGrid
Event logged in auth_logs

Authentication Flow:

Client submits credentials
Backend validates and checks lockout status
Password verified against hash
Access token (JWT, 15 min) generated
Refresh token generated and stored in user_sessions
Both tokens returned to client
Failed attempts increment failed_login_attempts
Account locked after 5 failures

Token Refresh Flow:

Client submits refresh token
Backend validates token hash in user_sessions
New access token generated
New refresh token generated (rotation)
Old refresh token revoked
New tokens returned

Security Architecture

Authentication & Authorization

JWT Token Strategy

Access Token: Short-lived (15 minutes), contains user claims
Refresh Token: Longer-lived (24 hours default, 7 days with “Remember Me”)
Token Storage:
- Access token: Memory/sessionStorage (frontend)
- Refresh token: httpOnly cookie or secure storage
- Server-side: Hashed in database for revocation

Password Security

Hashing: bcrypt with 12 rounds
Requirements:
- Minimum 8 characters (12+ recommended)
- Mixed case (upper and lower)
- Numbers and special characters
- Dictionary checking
- No email/company name inclusion

Account Protection

Rate Limiting: Per-endpoint limits on sensitive operations
- Registration: 5 attempts/hour per IP
- Login: 5 attempts/15 minutes per email
- Password reset: 3 attempts/hour per email
Account Lockout: 30 minutes after 5 failed login attempts
Session Management: Server-side session storage for revocation

Data Protection

Encryption

In Transit: HTTPS/TLS 1.3 for all communications
At Rest: Database-level encryption (provider-managed)
Passwords: Bcrypt hashed, never stored in plaintext
Tokens: Hashed before storage in database

Data Minimization: Only collect necessary data
Purpose Limitation: Clear purpose for each data field
Consent Tracking: Terms acceptance timestamp
Audit Trail: Comprehensive logging in auth_logs
User Rights: Foundation for access, portability, deletion

API Security

Request Validation

Schema Validation: Joi schemas for all inputs
Type Safety: TypeScript throughout
Sanitization: Input cleaning to prevent injection

CORS Configuration

Controlled origin whitelist
Credentials support for cookies
Appropriate headers for security

Rate Limiting

Implemented via express-rate-limit:

{
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 requests
  standardHeaders: true,
  legacyHeaders: false,
}

Audit & Monitoring

Auth Logs

All authentication events logged:

LOGIN_SUCCESS / LOGIN_FAILED
REGISTER_SUCCESS / REGISTER_FAILED
EMAIL_VERIFIED
PASSWORD_RESET_REQUESTED / PASSWORD_RESET_COMPLETED
TOKEN_REFRESH / TOKEN_REVOKED
LOGOUT

Log Data

User ID (if authenticated)
Email attempted
IP address
User agent
Success/failure status
Timestamp
Additional metadata (JSON)

Deployment Architecture

Vercel Deployment

Configuration

File: vercel.json

{
  "version": 2,
  "buildCommand": "npm install --prefix backend && npm install --prefix frontend && npm run vercel-build --prefix backend",
  "outputDirectory": "frontend/dist",
  "functions": {
    "api/server.ts": {
      "runtime": "@vercel/node@5.3.26"
    }
  },
  "routes": [
    { "src": "/api/(.*)", "dest": "/api/server.ts" },
    { "src": "/(.*)", "dest": "/api/server.ts" }
  ]
}

Build Process

Install backend dependencies (including dev dependencies)
Install frontend dependencies (including dev dependencies)
Build frontend (Vite) → frontend/dist
Compile backend TypeScript → JavaScript
Deploy serverless function (api/server.ts)
Deploy static assets to CDN

Environment Variables

Required on Vercel:

DATABASE_URL - PostgreSQL connection string
REDIS_URL - Redis connection string (optional)
JWT_SECRET - Secret for access tokens
JWT_REFRESH_SECRET - Secret for refresh tokens
SENDGRID_API_KEY - SendGrid API key
FROM_EMAIL - Sender email address
BASE_URL - Application base URL
NODE_ENV - Environment (production/staging)

Local Development

Docker Compose Setup

File: docker-compose.yml

Services:

PostgreSQL 15 (port 5432)
Redis 7 (port 6379)

Development Servers

Frontend: npm run dev --prefix frontend (Vite dev server, port 5173)
Backend: npm run dev --prefix backend (tsx watch mode, port 3001)

Database Setup

Start Docker services: docker-compose up -d
Run schema: psql -U postgres -d conformo_dev -f backend/db/schema.sql
Configure .env with local credentials

Integration Points

External Services

SendGrid (Email Service)

Purpose: Transactional emails

Integration:

Library: @sendgrid/mail
Authentication: API key
Templates: Programmatic (Italian)
Usage:
- Email verification
- Password reset
- Welcome emails
- Security notifications

Email Types:

Verification Email
- Subject: “Conferma il tuo account Conformo”
- 24-hour token expiry
- Italian template
Password Reset Email
- Subject: “Reset password Conformo”
- 1-hour token expiry
- Security notice

PostgreSQL Database

Purpose: Primary data store

Integration:

Library: pg (node-postgres)
Connection: Connection pool
Configuration: Environment variable DATABASE_URL

Redis Cache

Purpose: Session storage and rate limiting

Integration:

Library: redis
Connection: Standard client
Configuration: Environment variable REDIS_URL
Usage:
- Rate limit counters
- Session cache (optional)
- Temporary data storage

Internal Integrations

Frontend ↔ Backend

Protocol: REST over HTTPS

Authentication:

Bearer token in Authorization header
Format: Authorization: Bearer <access_token>

Response Format: JSON

{
  "success": true/false,
  "data": {},
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

Shared Code

Location: shared/

featureFlags.ts: Feature toggle system
- Shared between frontend and backend
- Enables/disables features without deployment

Scalability & Performance

Current Capacity

Serverless Architecture Benefits

Auto-scaling: Vercel functions scale automatically
No server management: Fully managed infrastructure
Geographic distribution: CDN for static assets
Pay-per-use: Cost-efficient for variable load

Performance Characteristics

Frontend Load Time: < 2s (first contentful paint)
API Response Time: < 500ms (average)
Database Queries: Indexed for common operations
Token Generation: < 100ms (bcrypt rounds optimized)

Scaling Considerations

Horizontal Scaling

✅ Already Supported:

Stateless API design
Session storage in database (no server affinity)
Serverless functions scale automatically

Database Scaling

Current: Single PostgreSQL instance

Future Options:

Read replicas for read-heavy operations
Connection pooling (PgBouncer)
Database sharding by tenant (if needed)
Caching layer (Redis) for frequent queries

Caching Strategy

Current: Minimal caching

Planned:

Redis caching for:
- User session data
- Frequently accessed user profiles
- Rate limit counters
CDN caching for:
- Static assets (already implemented)
- API responses (selective)

Performance Optimization

Frontend Optimizations

Code Splitting: React.lazy for route-based splitting
Asset Optimization: Vite’s built-in minification
Image Optimization: Lazy loading, responsive images
Caching: Service worker for offline support (future)

Backend Optimizations

Database Indexing: Strategic indexes on high-traffic queries
Query Optimization: Prepared statements, batch operations
Connection Pooling: Reuse database connections
Rate Limiting: Protect against abuse

Monitoring (Future)

Application performance monitoring (APM)
Real-time error tracking
Database query performance analysis
User experience metrics

Future Enhancements

Short-Term (Next 3-6 Months)

1. AI Compliance Wizard

Natural language interface for GDPR compliance
Step-by-step guided workflows
Italian language processing
Automated requirement analysis

2. Document Generation

Privacy policy generator
Cookie policy templates
Data processing agreements
Consent forms

3. Compliance Dashboard

Real-time compliance score
Action items and deadlines
Risk indicators
Progress tracking

Medium-Term (6-12 Months)

1. Data Subject Rights Portal

Access request management
Data portability tools
Deletion request workflows
Consent management system

2. Advanced Analytics

Compliance metrics over time
Risk trend analysis
User behavior analytics
Predictive compliance alerts

3. Mobile Application

React Native app for iOS/Android
Push notifications for critical actions
Offline support for key features
Mobile-optimized workflows

Long-Term (12+ Months)

1. Multi-Tenant Architecture

White-label solution for consultants
Isolated data per organization
Custom branding per tenant
Usage-based billing

2. Integration Marketplace

Third-party app integrations
API for external systems
Webhook system
OAuth provider for SSO

3. International Expansion

Multi-language support beyond Italian
Compliance frameworks beyond GDPR
Region-specific features
Local data residency options

Technical Debt & Improvements

Testing

Unit tests for critical services
Integration tests for API endpoints
End-to-end tests for user flows
Automated testing in CI/CD

DevOps

Automated deployment pipelines
Staging environment
Database migration system
Infrastructure as code

Observability

Structured logging
Distributed tracing
Metrics collection
Alert system

Document Maintenance

Update Process

This Technical Architecture Document should be updated when:

Major feature additions - New system components, services, or integrations
Architecture changes - Modifications to system design or technology stack
Technology updates - Upgrades to major dependencies or infrastructure
Security enhancements - New security measures or compliance requirements
Performance optimizations - Significant changes to scaling or caching strategies
Deployment changes - Updates to deployment process or infrastructure

Update Workflow

During Story Planning: Review if changes impact architecture
During Development: Document architectural decisions
Before PR Merge: Update relevant sections
During Review: Architecture changes reviewed by team
After Deployment: Verify documentation accuracy

Version History

Version	Date	Author	Changes
1.0	2025-10-16	System	Initial technical architecture document

Review Schedule

Quarterly Review: Full document review and updates
Bi-Annual Deep Dive: Architecture assessment and future planning
Annual Audit: Comprehensive review with stakeholder input

Appendix

Glossary

JWT: JSON Web Token - Standard for secure token-based authentication
GDPR: General Data Protection Regulation - EU privacy regulation
SME: Small and Medium Enterprise
CDN: Content Delivery Network
REST: Representational State Transfer - API architectural style
CORS: Cross-Origin Resource Sharing
bcrypt: Password hashing algorithm
SPA: Single Page Application

References

Contact

For questions or clarifications about this architecture document:

Repository: https://github.com/GrewingM/conformo
Issues: https://github.com/GrewingM/conformo/issues

Last Review: 2025-10-16
Next Review: 2026-01-16

Technical Architecture Document

Table of Contents

Executive Summary

Key Architectural Principles

Current Architecture

Architecture Overview

Current Deployment Model

Request Flow

Target Architecture

Planned Enhancements

1. AI Integration Layer (Planned)

2. Document Generation Pipeline (Planned)

3. Compliance Dashboard (Planned)

4. Data Subject Rights Management (Planned)

Migration Path

Technology Stack

Frontend Technologies

Backend Technologies

Database & Infrastructure

Development Tools

System Components

Frontend Components

1. Authentication Module

2. State Management

3. API Client Layer

4. Constants & Configuration

Backend Components

1. API Layer

2. Service Layer

3. Middleware & Utilities

4. Database Layer

5. Shared Components

Data Architecture

Database Schema

Users Table

User Sessions Table

User Tokens Table

Auth Logs Table

Data Flow

Security Architecture

Authentication & Authorization

JWT Token Strategy

Password Security

Account Protection

Data Protection

Encryption

Privacy Compliance (GDPR)

API Security

Request Validation

CORS Configuration

Rate Limiting

Audit & Monitoring

Auth Logs

Log Data

Deployment Architecture

Vercel Deployment

Configuration

Build Process

Environment Variables

Local Development

Docker Compose Setup

Development Servers

Database Setup

Integration Points

External Services

SendGrid (Email Service)

PostgreSQL Database

Redis Cache

Internal Integrations

Frontend ↔ Backend

Shared Code

Scalability & Performance

Current Capacity

Serverless Architecture Benefits

Performance Characteristics

Scaling Considerations

Horizontal Scaling

Database Scaling

Caching Strategy

Performance Optimization