Directory Overview
Frontend Structure
The frontend is a modern React application built with TypeScript, Vite, and TailwindCSS.Frontend Directory Layout
Key Frontend Files
main.tsx - Application Entry Point
main.tsx - Application Entry Point
The entry point that mounts the React application to the DOM:
frontend/src/main.tsx
- Uses React 18’s
createRootAPI - Wrapped in
StrictModefor development warnings - Imports global styles (including Tailwind)
App.tsx - Main Component
App.tsx - Main Component
The root component of your application:This is where you’ll build your UI. Replace this with your application logic.
frontend/src/App.tsx
index.css - Tailwind Setup
index.css - Tailwind Setup
Includes Tailwind CSS directives:This enables TailwindCSS utility classes throughout your application.
frontend/src/index.css
Frontend Technologies
React 18
Modern React with hooks, concurrent features, and automatic batching
TypeScript
Type-safe development with strict mode enabled for better code quality
Vite
Lightning-fast dev server with HMR and optimized production builds
TailwindCSS
Utility-first CSS framework for rapid UI development
Backend Structure
The backend is a RESTful API built with Go, Echo framework, and MongoDB.Backend Directory Layout
Key Backend Files
main.go - Application Entry Point
main.go - Application Entry Point
The main file that initializes the server, middleware, and routes:Key Features:
backend/main.go
- Auto-loads
.envfile viagodotenv/autoload - Configures Echo middleware: Logger, Recover, CORS
- Connects to MongoDB on startup
- Defines public API routes
users/model.go - User Data Model
users/model.go - User Data Model
Defines the User struct and database operations:Features:
backend/users/model.go
- Struct tags for JSON and BSON serialization
- Method receiver for creating users
- Helper functions for querying by email/phone
auth/controller.go - Authentication Logic
auth/controller.go - Authentication Logic
Contains the business logic for user registration and login:Security Features:
backend/auth/controller.go
- Bcrypt password hashing with cost factor 14
- User status validation
- UUID generation for user IDs
auth/auth.go - JWT Token Management
auth/auth.go - JWT Token Management
Handles JWT token generation and cookie management:Features:
backend/auth/auth.go
- JWT tokens with 24-hour expiration
- HTTP-only cookies for security
- HS256 signing algorithm
configs/db.go - Database Connection
configs/db.go - Database Connection
MongoDB connection and helper functions:Features:
backend/configs/db.go
- Global MongoInstance for database access
- Environment-based database naming
- Connection validation with ping
Backend Technologies
Go 1.21+
Modern Go with generics and improved performance
Echo v4
High-performance web framework with middleware support
MongoDB
NoSQL database with flexible document storage
JWT
Secure token-based authentication with bcrypt password hashing
Module Organization
The backend follows a module-based structure where each feature is organized into its own package:Auth Module
Purpose: Handles user authentication and authorization Files:auth.go: JWT token generation and cookie managementcontroller.go: Business logic for login and registrationroutes.go: HTTP request handlersconfigs.go: Authentication configuration
- User registration with password hashing
- User login with credentials validation
- JWT token generation and validation
- Session management via HTTP-only cookies
Users Module
Purpose: User data model and database operations Files:model.go: User struct and CRUD operations
- Define user data structure
- Create new users in database
- Query users by email, phone, or ID
- Update user information
Configs Module
Purpose: Application configuration and database connectivity Files:db.go: MongoDB connection and helper functionsenv.go: Environment variable accessors
- Establish MongoDB connection
- Provide database helper functions (insert, update)
- Load and expose environment variables
- Manage application configuration
Integrations Module
Purpose: External service integrations Files:paypack.go: Payment processing integrationtelegram-bot.go: Telegram notificationsuseplunk.go: Email service integration
- Connect to third-party APIs
- Handle payment processing
- Send notifications and emails
These integrations are optional and can be removed if not needed.
How the Pieces Fit Together
Request Flow
Here’s how a typical authentication request flows through the application:Echo Middleware
Request passes through middleware stack:
- Logger: Records request details
- Recover: Handles panics gracefully
- CORS: Validates origin and sets headers
Business Logic
processUserLogin in controller.go validates credentials:- Queries user from MongoDB via
users.GetUserByEmail - Checks user status
- Compares hashed password using bcrypt
- Returns user ID if successful
Database Interaction
Data flows from application code to MongoDB:Frontend-Backend Communication
The frontend and backend communicate via REST API:Environment Configuration
The application uses environment variables for configuration:backend/.env
APP_ENV: Environment (development/production) - affects database namingMONGODB_URI: MongoDB connection stringPORT: Server port (default: 8080)SESSION_KEY: Secret key for JWT signing (required)
REDIS_URL: Redis cache connectionPAYPACK_*: Payment integration credentialsUSE_PLUNK: Email service API keyTELEGRAM_*: Telegram bot credentials
Development Workflow
Adding a New Feature
Create Backend Endpoint
- Add a new handler in the appropriate module (or create a new module)
- Implement business logic in a controller function
- Register the route in
main.go
Create Frontend Component
- Create a new React component in
frontend/src/ - Make API calls using
fetchoraxios - Style with TailwindCSS utility classes
Example: Adding a Profile Endpoint
Backend (backend/main.go):
Build and Production
Frontend Build
frontend/dist/:
- Minified JavaScript and CSS
- Tree-shaken dependencies
- Optimized assets
Backend Build
main:
- Statically linked
- No runtime dependencies (except MongoDB)
- Cross-platform compatible
Next Steps
Quick Start
Get the project running locally in minutes
Add Authentication UI
Build login and registration forms in React
Create Custom Endpoints
Extend the API with your own routes and handlers
Deploy to Production
Learn how to deploy your full-stack application