Skip to content

Commit ae718df

Browse files
remote-swe-userremote-swe-app[bot]tmokmss
authored
docs: add AmazonQ.md knowledge base file (#50)
This PR adds the AmazonQ.md knowledge base file that contains important information about the project structure, coding conventions, and best practices. The file provides: - Project overview and architecture details - Directory structure explanations - Technology stack information - Commonly used commands - Development workflow - Best practices for working with the codebase This will help Amazon Q understand the repository better when assisting with development tasks. --------- Co-authored-by: remote-swe-app[bot] <123456+remote-swe-app[bot]@users.noreply.github.com> Co-authored-by: Masashi Tomooka <tmokmss@users.noreply.github.com>
1 parent c029c2f commit ae718df

1 file changed

Lines changed: 137 additions & 0 deletions

File tree

AmazonQ.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Serverless Full Stack WebApp Starter Kit Knowledge Base
2+
3+
This file provides important information about the Serverless Full Stack WebApp Starter Kit repository. AI agent references this to support its work on this project.
4+
5+
## Project Overview
6+
7+
This project is a full stack webapp starter kit leveraging AWS serverless services, featuring:
8+
9+
- Next.js App Router on AWS Lambda
10+
- CloudFront + Lambda function URL with response stream support
11+
- End-to-end type safety (client to server)
12+
- Cognito authentication
13+
- Real-time notifications
14+
- Asynchronous job queue
15+
- Instant deployment via AWS CDK
16+
17+
## Project Structure
18+
19+
The project consists of two main components:
20+
21+
1. **WebApp** - `/webapp` directory
22+
- Next.js application with App Router
23+
- Frontend UI and server components
24+
- Server actions
25+
- TypeScript + React
26+
- Tailwind CSS for styling
27+
28+
2. **CDK (AWS Cloud Development Kit)** - `/cdk` directory
29+
- Infrastructure as Code definitions
30+
- AWS resource provisioning
31+
- Deployment configurations
32+
33+
### WebApp Structure
34+
35+
```
36+
/webapp/src/
37+
├── app/
38+
│ ├── (root)/
39+
│ │ ├── components/ (feature-specific components)
40+
│ │ ├── actions.ts (server actions)
41+
│ │ ├── schemas.ts (validation schemas)
42+
│ │ └── page.tsx (main page)
43+
│ ├── api/
44+
│ ├── auth-callback/
45+
│ └── sign-in/
46+
├── components/ (shared components)
47+
├── hooks/
48+
├── jobs/
49+
├── lib/
50+
└── middleware.ts
51+
```
52+
53+
## Technology Stack
54+
55+
- **Frontend**: React, Next.js, Tailwind CSS
56+
- **Backend**: Next.js App Router, Server Actions, AWS Lambda
57+
- **Database**: Amazon Aurora PostgreSQL Serverless v2 with Prisma ORM
58+
- **Authentication**: Amazon Cognito
59+
- **Real-time**: AWS AppSync Events
60+
- **Infrastructure**: AWS CDK, CloudFront, Lambda, EventBridge
61+
62+
## Coding Conventions
63+
64+
- Use TypeScript for type safety
65+
- Feature-based directory structure
66+
- Function components with hooks for React
67+
- Server actions for backend logic
68+
- Zod for data validation
69+
- Prisma for database interactions
70+
71+
## Commonly Used Commands
72+
73+
### WebApp
74+
75+
```bash
76+
# Development server (with Turbopack)
77+
cd webapp && npm run dev
78+
79+
# Build the web application
80+
cd webapp && npm run build
81+
82+
# Formatting
83+
cd webapp && npm run format
84+
85+
# Check formatting
86+
cd webapp && npm run format:check
87+
88+
# Linting
89+
cd webapp && npm run lint
90+
```
91+
92+
### CDK
93+
94+
```bash
95+
# Build the CDK project
96+
cd cdk && npm run build
97+
98+
# Deploy the application to AWS
99+
cd cdk && npm run cdk deploy
100+
101+
# Check for changes in the infrastructure
102+
cd cdk && npm run cdk diff
103+
```
104+
105+
## Development Flow
106+
107+
1. Create a branch for a new feature or bug fix
108+
2. Implement changes and test locally
109+
3. Run format and lint checks
110+
4. Create a PR with title and description in English and ensure CI passes
111+
5. Request review when the PR is ready
112+
113+
## Best Practices
114+
115+
1. **Directory Organization**:
116+
- Group feature-specific components, actions, and schemas in the same directory
117+
- Keep shared components in the top-level components directory
118+
119+
2. **Code Quality**:
120+
- Use TypeScript for type safety
121+
- Validate inputs with Zod schemas
122+
- Follow Next.js server/client component patterns
123+
124+
3. **Authentication**:
125+
- Use the built-in auth mechanisms for protected routes
126+
- Follow Cognito authentication patterns
127+
128+
4. **Database Access**:
129+
- Use Prisma for database operations
130+
- Keep database logic in server actions
131+
132+
## Troubleshooting
133+
134+
- **Next.js Errors**: Ensure proper separation of client/server components
135+
- **CDK Deployment Issues**: Check AWS credentials and permissions
136+
- **Authentication Problems**: Verify Cognito user pool configuration
137+
- **Database Connection Errors**: Check Prisma schema and connection string

0 commit comments

Comments
 (0)