Docs
Introduction
System Architecture
Module Convention
Scalar Convention
Codebase
Introduction
System Architecture
Module Convention
Scalar Convention
Codebase
Write once, deploy everywhere
Why do we need to create multiple separate projects to implement a single business?
Isn't it confusing and inefficient to develop backend, frontend, Android, and iOS separately? Can't we do everything at once?
Akan.js is a full-stack framework that allows you to deploy your service to backend, frontend web, Android, and iOS with a single code written.
With a single code written with type-safe way, you can deploy your service to backend, frontend web, Android, and iOS.
With this, you no longer need to struggle with various platforms. You can focus on developing your service and providing a better user experience.
Make Developer a Businessman
Akan.js helps you minimize technical code and focus on implementing business logic.
Akan.js also provides many convenient features for building applications and provides installable libraries to provide best practices for business development.
Workspace (monorepo)
Akan.js is a monorepo structure that allows a single organization (team) to develop multiple apps on a single repository (workspace). A single workspace contains multiple apps (apps) and common libraries (libs).
App(apps): Standalone application that can be deployed to all platforms (web, mobile, server, etc.)
Common library(libs): Provide common features that can be used by multiple apps. For example, login, payment, notification, chat, etc. are common features used in various apps. By providing these features as common libraries, developers can reuse them to reduce development time.
├── apps/ # Application list│ └── appA/ # Individual application│ └── appB/ # Individual application└── libs/ # Library list ├── shared/ # Shared library ├── util/ # Utility library └── [other libs]/ # Other specific librariesWhen you run `akan create-workspace`, shared and util libraries are installed by default. These libraries are common libraries that can be used by all apps.
You can use common libraries in your created application (e.g. myapp). For example, you can use the shared library to provide admin page and file upload tool.
80:20 rule
A healthy workspace maintains a structure where 80% of the code is shared between apps, and 20% is specific to each app.
However, you don't have to force yourself to follow the rule. Just maintain the workspace with your heart, and the ratio will naturally be adjusted as you maintain it.
Workspace file structure
To efficiently arrange server, client, and common code, the apps and libs structure has the following identical structure.
The server is implemented as a node.js application that is executed in the main.ts file, and the client is implemented as a Next.js app router-based file-based routing.
└── {apps,libs}/ # Application or library code └── {appA,libA}/ # Individual application or library ├── app/ # File based routing (Only in apps) ├── base/ # Base code (not-modularized) ├── common/ # Common code (modularized) ├── env/ # Environment variables ├── lib/ # Domain modules ├── nest/ # Server-side logic code ├── next/ # Client-side logic code (modularized) ├── public/ # Assets files ├── ui/ # UI code (modularized) ├── akan.config.ts # Application configuration ├── main.ts # Backend entry point (Only in apps) ├── client.ts # Client-side barrel file └── server.ts # Server-side barrel fileTo run the server and client, each server.ts and client.ts files implement the modularized code as a single file (barrel file).
To implement this, the server, client, and common files are separated, and the file rules are taken, and roughly expressed as follows.
By arranging the server, client, and common files in accordance with the file rules, you can implement an extensible and reusable structure. You don't need to understand all the rules now. As you write code in the future practice, you can understand one by one. The most important thing is to understand where the code you want to implement is located in the server, client, and common files.
For example, if you want to implement a password-based login feature, the component that receives the ID and password is a client feature. The function of encrypting and storing it is a server feature, and checking if the password is more than 8 characters is a common feature needed by both.
Collab cohesively
Akan.js provides strict file rules to ensure that everyone implements the same way.
This allows developers to collaborate seamlessly and have their colleagues take over their work while they take a vacation.
The most common tasks in a workspace are 1) writing pages that are delivered to users and 2) writing domain modules that implement business concepts. To do this, file rules are defined.
Page file convention - File-based routing
The page is a file that implements the page and layout that are implemented according to the url path. The page file is implemented in a folder structure, and is implemented in the same way as Next.js app router.
└── apps/ # Application list └── appA/ # Individual application └── app/ # File based routing (Next.js app router) ├── pageA/ # Page folder │ ├── layout.tsx # Layout component │ └── page.tsx # Page component └── pageB/ # Another page ├── layout.tsx # Layout component ├── page.tsx # Page component └── [param]/ # Dynamic segment └── layout.tsx # Layout component └── page.tsx # Page componentDomain module file convention
The domain module is a representation of a single domain in the business. For example, there are user management, order management, payment management, etc. To represent this, it must be implemented in a structured form across the entire system, including data structure, service logic, and user UI.
└── {apps,libs}/ # Application or library code └── {appA,libA}/ # Individual application or library └── lib/ # Domain modules └── moduleA/ # Feature module ├── moduleA.constant.ts # Types and schemas ├── moduleA.dictionary.ts # Translations ├── moduleA.document.ts # Document ├── moduleA.service.ts # Business logic ├── moduleA.signal.ts # API endpoints ├── moduleA.store.ts # State management ├── moduleA.Template.tsx # Form UI ├── moduleA.Unit.tsx # Overview UI ├── moduleA.Util.tsx # Utility UI ├── moduleA.View.tsx # Detail view UI └── moduleA.Zone.tsx # Integration UIA domain is a complex organism that operates like a single domain. From the schema definition in the constant file to the integration component of the Zone, it can be managed in a single folder, allowing for a version gap between the backend and frontend.
Who should use?
It is suitable for developers who want to create a product-level solution and deliver it to customers.
Live products need to be managed and operated continuously. Akan.js provides an environment where one developer can operate multiple projects at the same time, and multiple developers can collaborate on a single project as a single body.
A framework always has a trade-off. If it is easy to use, it may be difficult to advance, and if it is diverse, it may be difficult to collaborate.
What we focus on
✅ Abstraction of interfaces for representing business
✅ Continuous stable reflection and update of the latest trends in technology for product-level quality
✅ Consistent workflow and best practices through strict and unified rules
What we not focus on
❌ Representing unnecessary technical details unrelated to business
❌ Unstable technical reflection and unnecessary optimization
❌ Allowing multiple approaches to work
Work backward
Programming is to create business value by efficiently connecting our lives and customers' lives. Define the problem, create a product-level solution quickly through Akan.js, and easily deliver it to customers!
Akan.js is always open to your feedback. If you have any questions, please leave an issue on GitHub. When you are working for customers, we are working for you.