How tonikiri666/hassu works
Project type and purpose
• Full-stack web application “Hassu”
• Front-end: Next.js React UI, server-rendered pages, static assets and API routes
• Back-end: AWS Lambda-based API (Serverless Framework or CDK), handling project management workflows, document generation, file storage, messaging and search
• Shared domain code in “common” and reusable Lambda layers
File structure analysis
• Top-level directories
• backend/ – all Lambda handlers, business logic, integration with DynamoDB, S3, SQS, OpenSearch, external systems (Velho, suomifi, MML, PRH), PDF generation
• src/ (root) – Next.js app: pages/, components/, hooks/, services/, API routes under pages/api
• common/ – shared TypeScript types, GraphQL schema stubs, validation, utilities used by both front- and back-end
• layers/ – AWS Lambda layers (e.g. lambda-base)
• deployment/ – CDK/Serverless infra definitions, pipeline scripts, IAM setup, localstack config
• graphql/ – GraphQL schema and codegen configuration
• cypress/ – end-to-end tests
• Patterns
• Backend: handler/adaptor pattern per feature (e.g. HyvaksymisEsitys, aloitekuulutus)
• AWS service clients organized under aws/, sqsEvents/, personSearch/, projektiSearch/
• Separation of concerns: “handler” (Lambda entry point) → “service” (business logic) → “database” (persistence) → “adapter” (external API transform)
• Front-end: page/component/hook/service layers, Next.js API routes for SSR and client API proxy
README insights
• Deploys via npm scripts: deploy:backend, deploy:frontend, deploy:app
• Relies on AWS Systems Manager Parameter Store for secrets and configuration
• CI/CD pipeline bootstrapped via deploy:pipeline
• GraphQL code generation step
a. Main components
• Front-end (Next.js app)
• API Gateway (or Next.js API routes)
• AWS Lambda functions (grouped by domain modules)
• AWS SQS queues (event bus for file processing, zip tasks)
• AWS S3 buckets (file storage, PDF assets)
• AWS DynamoDB (projekti data, short URL lookup)
• AWS OpenSearch (projektihaku, muistuttaja and omistaja search)
• AWS Lambda layers (shared utils)
• CDK/Serverless Framework (infrastructure as code)
• External services: Velho APIs, suomifi WS, MML, PRH
• CI/CD Pipeline (CodePipeline/BuildSpec via deployment/)
b. Relationships and interactions
1. User’s browser → CloudFront → Next.js front-end
2. Front-end → API Gateway or Next.js API routes → Lambda functions
3. Lambda interacts with DynamoDB for CRUD, S3 for file I/O, SQS to enqueue background tasks
4. File events on SQS → Lambda “sqsEventHandlerLambda” → file persistence, zip generation, notifications
5. DynamoDB streams → Lambda “projektiSearch” → OpenSearch indexing
6. Lambdas call external WS/APIs (Velho, suomifi, MML) via aws/clients or generated SDK under backend/src/velho
7. PDF generation: Lambda “asiakirjaHandler” → file stored to S3 → URL returned to front-end
8. CDK/Serverless deploys all resources, IAM roles, pipelines, CloudFront distributions
c. Architectural patterns and principles
• Serverless microservices: each domain feature as separate Lambda
• Event-driven: SQS, DynamoDB Streams
• Adapter/Mapper layers for external systems and for API⇄DB transformations
• Infrastructure as Code: CDK or serverless.yml scripts
• Shared business logic in Lambda layers and common/ package
d. Key technologies and frameworks
• Next.js, React, TypeScript
• AWS Lambda, API Gateway, SQS, S3, DynamoDB, OpenSearch
• CDK/Serverless Framework for infra
• Cypress for E2E
• GraphQL codegen (common/graphql)