--- url: /what-is-handbook.md --- # What is the OSBR Handbook? \[\[TOC]] ## 1. About Us We are a development company working in collaboration with our parent company, Oz Co. Ltd., a creative media agency in Japan. Together, we bring ideas to life through campaigns, website development, advertising, and graphic design. As a development team, we research and test emerging technologies to drive business growth and innovation. Our focus is on staying ahead of industry trends, making sure clients stay ahead in the digital space. Beyond digital services, we believe in turning ideas into reality. Through our [Envisioned Projects](strategy.md#envision-project), we push creative and technological boundaries with hands-on, real-world initiatives. Explore our latest work on our [website.](https://www.osbrjp.com/en/) ## 2. Vision and Values OSBR strives to grow into a **global enterprise** that goes beyond providing technical solutions. We see a future where technology is made to form the **foundation of new products and innovations**. We inject meaningful value into every project we create through our business model. Expanding from **Oz in Japan**, our goal is to establish OSBR as a **powerhouse of creative media** in Malaysia while pioneering new products and constructing reputable business ideas. Our journey is built upon three core values: **Be Nice, Be Kind, Be Strong**. * Think wholeheartedly, about consumers, users, and the colleagues you work with. * Offer a helping hand, when others are in need. * Cultivate strength, because only through strength can we uplift others and make a difference. It all begins here, in **Kuala Lumpur, Malaysia**. ## 3. The Handbook At OSBR, we're actively shaping our **organizational culture** from the ground up. As a newly established company, we’re committed to building a strong foundation that reflects our **values, vision, and workflows**. By referring to the [GitLab model](https://www.hbs.edu/faculty/Pages/item.aspx?num=57917), we have committed to develop the OSBR Handbook, a comprehensive guide publicly accessible as you can read this now. While our primary goal is to cultivate a strong internal culture, our open-access policy may also help refine OSBR’s identity by incorporating feedback from clients, partners, and potential collaborators. In the **AI-Agent era**, maintaining **context-aware knowledge** is crucial. That’s why we write for both humans and AI—ensuring accuracy, accessibility, and seamless collaboration at every level of our projects, be it repository, pull requests or launched products. --- --- url: /strategy.md --- # Strategy Overview \[\[TOC]] ## 1. Vision #### In a world where businesses make people happy, regardless of its size, thrive more and more. The limits to what a person can do may be small and limited, but everyone’s smartphone has the power to communicate with the world. Gradually, it has made opportunities more equal. Small things may turn to bigger opportunities. We believe it’s not a matter of who provides it, but rather, a good product will spread quickly and widely regardless. ## 2. Value Delivery Model We define our business domain through the Value Delivery Model, illustrated in the diagram below—a dynamic framework where we innovate and create value by seamlessly integrating the physical and digital realms. ```mermaid --- title: Value Delivery Model --- graph BT; subgraph OSBR direction BT SA[Solution Architect] -- "operation workforce" --> ED[Experience Designer]; SD[Software Developer] -- "implementation workforce" --> ED; R[Researcher] -- "proposal materials" --> SA; R -- "technological insights" --> SD; end ED -- "proof of concept (PoC)" --> EFR[[Envision Project]]; subgraph CP[Client / Partner] direction BT ED -- "semi-custom solution" --> CDE[Digital Interface]; CCV[Competitive Resource] end subgraph Collaborator CD[Communication Design / Marketing Research] --"exective support"--> CDE end EFR -. "scaling up" .-> CS; CCV -- "core value" --> CS[[Commercial Service]]; CDE -- "liquidity enhancement" --> CS; EFR -- "experimental field research" --> U[Consumer / Business]; CS -- "enriched engagement" --> U; ``` Since our founder established "beatfast" (later renamed "Saturday Inc.") in 2013, we have been working on conceptual internet services designed to develop software artifacts and gain business domain insights. These assets enable us to deliver semi-custom solutions to our clients in Japan, not only providing OEM but also leveraging our knowledges to drive their businesses forward. As OSBR, we expanded our visionary journey to "off-screen", as demonstrated by our projects [onray](https://www.weareonray.com/en) and [Time Crunch](https://www.wearetimecrunch.com/). These initiatives have provided invaluable feedback, inspiring us to envision even more innovative services while continuously refining our approach to deliver intuitive, impactful, and user-centered experiences that bridge the gap between the physical and digital worlds. Leveraging this foundation—and without altering our core vision—we have shifted our mid-term focus toward enhancing digital experiences through the application of large language models (LLMs). From the experimental-to-commercial strategy we established as beatfast to the expansion into the physical domain as OSBR, we continue to evolve. By introducing innovative services powered by LLMs, we aim to empower our client businesses and accelerate their growth. ## 3. Business Model Our business model is structured to align with the Value Delivery Model described above, ensuring sustainable operations while fostering innovation. The model comprises three key strategies, each designed to play a unique and complementary role in achieving our mission: ### 3-1. Envision Project OSBR initiates and executes experimental research projects, referred to as "Envision Project". These projects are delivered directly to consumers or businesses, generating valuable feedback that refines our "Semi-Packaged Solution". The "Semi-Packaged Solution" is a flexible framework composed of software artifacts and domain insights that can be tailored to meet the specific needs of a client. This model enables us to leverage our expertise to create innovative solutions while ensuring alignment with client objectives and retaining creative control over the project. ```mermaid --- title: Envision Project Model --- graph TB; OSBR([OSBR]) -- "PoC planning" --> ES[[Envision Project]]; CB -- "feedback / revenue" --> ES; ES -- "delivery" --> CB([Consumer / Business]); ES -- "feedback condensation" --> SPS[Semi-Packaged Solution]; ``` #### Sponsored Envision Project In addition to our In-House Envision Project Model, we also offers a Sponsored Envision Project Model. OSBR undertakes experimental research projects tailored to the specific needs of clients. While OSBR retains ownership of the projects, clients are granted primary acquisition rights. This approach is not solely focused on establishing profitability as a self-sustaining project but also aims to enhance non-monetary value, such as elevating brand image, increasing awareness, and fostering user engagement. ```mermaid --- title: Sponsored Envision Project Model --- graph TB; C([Client]) -- "sponsor" --> OSBR OSBR([OSBR]) -- "PoC planning" --> ES[[Envision Project]]; OSBR -- "tailor" --> SPS[Semi-Packaged Solution]; SPS -- "branded as" --> ES; CB -- "feedback / revenue" --> ES; ES -- "deliver" --> CB([Consumer / Business]); ``` ### 3-2. Client Work for Commercial Service OSBR collaborates with clients to develop commercial services by leveraging its field knowledge and semi-packaged solutions. These services enable clients to maximize the value of their competitive resources while enhancing liquidity by reshaping value into forms that provide better experience and ease for users. The services are designed to deliver refined, user-focused experiences, ensuring flexibility in scaling and monetization. Feedback from these services further contributes to OSBR’s innovation cycle, driving continuous improvement and alignment with market demands. ```mermaid --- title: Client Work Model --- graph TB; C([Client]) -- "commission" --> OSBR OSBR -- "ownership" --> C; C -- "competitive resource" --> ES[[Commercial Service]]; OSBR -- "tailor" --> SPS[Semi-Packaged Solution]; SPS -- "branded as" --> ES; CB -- "feedback / revenue" --> ES; ES -- "deliver" --> CB([Consumer / Business]); ``` ### 3-3. Ownership Transfer In cases where clients wish to take full control of an envision project, OSBR facilitates ownership transfer, providing the necessary resources and support for a seamless transition. This model empowers clients to continue developing projects independently while benefiting from OSBR’s foundational contributions. ```mermaid --- title: Ownership Transfer Model --- graph TB; C([Client]) -- "commission" --> OSBR([OSBR]); OSBR([OSBR]) -- "ownership" --> C IHSES[[Envision Project]] -- "rebranded as" --> CS[[Commercial Service]]; C -- "tailor" --> IHSES; CS -- "deliver" --> CB([Consumer / Business]); CB -- "feedback / revenue" --> CS; ``` --- --- url: /code-of-conduct.md --- # OSBR Code of Conduct Creating a professional, inclusive, and respectful environment is a core value at OSBR. This Code of Conduct ensures that all members can work and collaborate in a welcoming and supportive space. ::: info Scope This Code of Conduct applies within all project spaces, including repositories, forums, and events. It also extends to public spaces when representing OSBR. ::: ## Our Commitment At OSBR, we are committed to fostering a working environment that welcomes **everyone**, regardless of race, gender, disability, religion, appearance, opinions, or expressions. We believe in treating all individuals with respect and fairness while honoring personal beliefs. ## Company Standards To maintain a positive and productive environment, we encourage: * ✔️ Inclusive and considerate language. * ✔️ Respect for diverse perspectives and experiences. * ✔️ Open-mindedness when receiving feedback. * ✔️ A focus on collective well-being. * ✔️ Kindness, empathy, and professionalism in interactions. ## Unacceptable Behavior To ensure safety and respect, the following actions are **prohibited**: * ❌ Sexualized language, imagery, or unwelcome advances. * ❌ Harassment, insults, trolling, or personal attacks. * ❌ Sharing private or confidential information without consent. * ❌ Any conduct deemed inappropriate in a professional setting. ## Enforcement We take violations seriously. If you witness or experience unacceptable behavior, report it to **info@osbrjp.com**. All reports will be reviewed, and appropriate action will be taken to maintain a safe and respectful space. ## Attribution This Code of Conduct is inspired by the **GitLab Community Code of Conduct**, available at [GitLab Code of Conduct](https://about.gitlab.com/community/contribute/code-of-conduct/). ## Policy Updates *Last updated: **February 25, 2025*** --- --- url: /talent-acquisition.md --- # Talent Acquisition :::info Überprogrammer The Übermensch, a concept from Nietzsche’s philosophy, represents an individual who transcends limitations. Just as the Übermensch rejects complacency, developers challenge outdated methodologies and shape the future of the digital landscape. ::: \[\[TOC]] ## 1. OSBR and Programmers Programmers thrive in dynamic, hands-on environments, and that’s exactly what we offer. As a startup deeply embedded in emerging technologies and real-world problem-solving, we provide a space where innovation and collaboration go hand in hand. Here, we don’t just follow industry trends but instead, we experiment with them. Whether it’s AI, cloud computing, or new development frameworks, we are aiming to explore technologies that shape the future. Why should this interest you? ### 1-1. Hands-On Collaboration Programmers shouldn't just be assigned to repetitive tasks or minor bug fixes. AI is already automating those tasks anways. The belief in learning by doing is something that should be hold on to. Developers should be involved in building, testing, and iterating on real projects. Whether it’s prototyping new features, optimizing performance, or solving complex challenges. To actively contribute to meaningful work that has an impact is the point. Initiative and problem-solving are most welcomed. That way, every developer gets to experience the full software development lifecycle, rather than just isolated fragments of it. ### 1-2. Exposure and Cultural Exchange At OSBR, gaining exposure to different programming practices, workflows, and work cultures, particularly from Japan and Malaysia is a bonus treat. ```mermaid --- title: Cultural Exchange --- graph TD; A[Exposure to Different Programming Practices] --> B[Understanding Workflows] A --> C[Learning Work Cultures] B --> D[How Teams Operate Internationally] C --> D D --> E[Understanding Different Approaches ] E --> F[Adapting Best Practices from Diverse Backgrounds] ``` This cultural exchange helps developers broaden perspectives in learning how teams operate internationally, understanding different approaches to software development, and adapting best practices from diverse backgrounds. ### 1-3. A Platform to Innovate and Grow The hallmark of a programmer is creativity in problem-solving and technical curiosity. Developers should have freedom to experiment with new technologies, propose ideas, and take ownership of projects. We believe in fostering an environment like that. For example, an environment where one can: * Test new tools and frameworks. * Contribute beyond code. * Gain mentorship and feedback. The goal is to create a space where programmers don’t just execute tasks, but actively shape the future of technology with their team. ## 2. The Mindset We Value in the AI Era Like many early-stage startups, we are facing challenges in attracting top talent. However, with the rise of LLMs, the way we define skill as an effective capability is dynamically shifting. Even those who were once considered top professionals are now being pushed to adapt and transform. While past achievements certainly deserve recognition, we believe the following factors are especially important at OSBR: ### 2-1. A Passion for Innovation Using AI An ability to critically evaluate AI-generated artifacts, neither unconditionally accepting nor outright rejecting them, but discerning whether they are accurate or flawed, beneficial or harmful. In other words, it is a mindset that seeks to go beyond AI artifacts by leveraging AI itself in creating greater value rather than merely replicating it. To pursue true innovation is to demand intellectual curiosity, creativity and perseverance, which AI-generated artifacts alone can never satisfy. Those who thrive in this field are not merely replicators of AI-generated output but active participants in shaping the future of technology. ### 2-2. A Careful Insight into Semantic Integrity A linguistic skill to enrich contextual vocabularies while avoiding ambiguity, ranging from individual words to broader conceptual frameworks, and from upstream to downstream processes. We prioritize this skill because we believe that software design is, in essence, the design of a domain-specific language (DSL) that is sufficiently descriptive for building software. In this context, the meaning of "language" expands as follows: #### Descriptive Languages | Format | Name | Comment | | --------------- | -------------------- | --------------------------------------------------------------------------- | | Character-Based | Natural Language | Descriptive across all levels of abstraction. | | Character-Based | Programming Language | Executable as a formal expression with no ambiguity. | | Graphical | Graphic Image | Represents an aspect of an object visually. | | Graphical | Movie | Provides a more immersive representation through time-based transformation. | These languages capture different aspects of an object from various perspectives. Ultimately, the key concern is not syntax but semantics. With a careful understanding of semantic integrity, we can describe objects with greater confidence. Otherwise, both humans and AI risk losing their way in ambiguity. ### 2-3. Emotional Intelligence Over Raw Intelligence In a world increasingly shaped by AI, emotional intelligence (EQ) matters more than ever. While technical skills and intellect (IQ) are valuable, the ability to understand, empathize, and connect with others is what truly drives meaningful collaboration and leadership. Empathy is not just an inherent trait but a skill that can be developed. Being kind, supportive, and strong at the same time is essential in any professional environment. Leadership, in particular, demands emotional resilience, not only in making sound decisions but also in maintaining a positive and composed demeanor. After all, a leader’s attitude sets the tone for the entire team. ### 2-4. A Directive Mindset for Decision-Making A sense of directive thinking over binary thinking—in other words, a thoughtful mindset that seeks "better or worse" rather than simply concluding "right or wrong." In the dark, we may walk straight with a light in our hand, illuminating the ground to ensure each step. However, we lose our way when we raise our heads, letting the light sweep from east to west instead of guiding our path. In reality, the best direction is often somewhere between right and left, and the same applies to every software decision. Decision-making is not about finding the perfect answer but about choosing the best course of action in a given context. A directive mindset enables us to move forward despite uncertainty, refining our approach as we learn from experience. ### 2-5. A Strong Sense of Responsibility Some argue that the last remaining job for humanity will be to take responsibility for AI’s failures. This may sound dystopian, yet it is a compelling notion as AI agents increasingly demonstrate their ability to take over intellectual tasks. However, this is not necessarily a pessimistic outlook as long as we can assess and control AI’s outputs. Rather than competing with AI in producing ever-faster and more advanced results, it is more reasonable for humanity to focus on guiding and overseeing its development. Ultimately, responsibility cannot be shifted onto AI itself. No matter how advanced AI becomes, it lacks true agency or accountability. This makes individual responsibility more important than ever, while ensuring that when problems arise, we have the ability to recognize, address, and resolve them effectively. ### 2-6. Communication, Teamwork and Collaboration A brilliant idea alone is not enough. Its impact depends on how well it is communicated and implemented through teamwork. Strong communication skills help ensure clarity, reduce misunderstandings, and foster productive collaboration. Teamwork is an essential part of every successful project. The ability to work harmoniously with colleagues, provide constructive feedback and adapt to different working styles leads to better solutions. At OSBR, we value individuals who actively contribute to a culture of open communication, respect and shared problem-solving. ## 3. Roles & Expectations OSBR seeks builders, innovators, and problem-solvers. If you're interested in shaping the backbone of an application, designing seamless user experiences, or pushing the boundaries of AI, we are too. There's a strong sense of collaboration over hierarchy here. That means your ideas matter, and we expect you to speak your mind! ### 3-1. Roles Here's a brief description of some roles that are available in our team. Which one describes you best? *** #### Backend Developer * You're the architect. You enjoy designing efficient systems, and making things work behind the scenes. | **What You’ll Do** | **You’ll Thrive If You...** | | ----------------------------------------------------------- | ------------------------------------------------------------- | | Design and maintain APIs that power our applications. | Enjoy working with languages like Python, Go, or Node.js. | | Optimize databases for speed, reliability, and scalability. | Have experience with databases (SQL, NoSQL). | | Work with cloud services to ensure smooth deployments. | Are comfortable with cloud platforms like AWS, GCP, or Azure. | * Working Conditions: | **Category** | **Details** | | ------------- | ------------------------------------------------- | | Location | On-site at the office | | Hours | Standard working hours with some flexibility | | Tech Stack | Primarily Python, Go, PostgreSQL, FastAPI | | Collaboration | Works closely with frontend engineers and AI team | *** #### Frontend Developer * You're the artist. You like turning ideas into beautiful and functional user interfaces. You care about design and making the web feel seamless. | **What You’ll Do** | **You’ll Thrive If You...** | | -------------------------------------------------------------------- | ------------------------------------------------- | | Develop engaging, responsive user interfaces. | Love working with JavaScript, React, or Vue.js. | | Ensure a smooth, fast, and accessible experience for users. | Have an eye for UI/UX and pixel-perfect design. | | Work with designers and backend developers to bring visions to life. | Enjoy crafting smooth animations and transitions. | * Working Conditions: | **Category** | **Details** | | ------------- | ---------------------------------------------------- | | Location | On-site at the office | | Hours | Standard working hours with occasional flexibility | | Tech Stack | Primarily JavaScript, React, TypeScript, TailwindCSS | | Collaboration | Works closely with designers and backend engineers | *** #### AI Engineer * You’re the innovator. Your fascination towards AI and its potential to revolutionize the way we work and live makes you eager to build. | **What You’ll Do** | **You’ll Thrive If You...** | | -------------------------------------------------------- | ---------------------------------------------------------------------- | | Develop and fine-tune AI models. | Have experience with Python and frameworks like TensorFlow or PyTorch. | | Work with large datasets to extract meaningful insights. | Enjoy working with data and optimizing machine learning models. | | Integrate AI into applications to enhance automation. | Love experimenting with AI-powered solutions. | * Working Conditions: | **Category** | **Details** | | ------------- | -------------------------------------------------------------- | | Location | On-site at the office | | Hours | Standard working hours, with flexibility depending on projects | | Tech Stack | Primarily Python, TensorFlow, PyTorch, cloud-based AI tools | | Collaboration | Works with backend teams and data | *** ### 3-2. Expectations Although everyone carries a designated title, at OSBR, roles are not rigid boxes. We believe that programmers grow best when they have the freedom to explore different areas. Here's how we do it here at OSBR: * Engineers are encouraged to take part in cross-functional projects beyond their primary role. * Internal hackathons and knowledge-sharing sessions helps the team explore different fields. * We emphasize mentorship and peer learning, so junior engineers can get tips and valuable insight. * Everyone is expected to actively contribute to problem-solving, not just within their domain but across the team. Collaboration is at the heart of what we do. Projects are rarely built in isolation, and working closely with different teams is part of the process. Titles are starting points rather than limitations. ### 3-3. Benefits & Growth When you build software, you're also building a career. The general belief is that when engineers are given the right environment, they can achieve remarkable things. That’s why we invest in ensuring everyone has the support they need to thrive. | **Benefit** | **Details** | | ---------------------------- | ------------------------------------------------------------------- | | Skill Development | Sponsoring online courses and training sessions | | Career Growth | Possibility of promotions and internal mobility within teams. | | Mentorship & Learning | Work closely with others and learning from real-world experience. | | Allowance | Travel and medical allowance are provided | | Performance-Based Incentives | Competitive salary with performance bonuses based on contributions. | | Equipment | Equipment that are up-to-par and modern . | | Project Variety | Opportunities to work on AI, backend, frontend, or DevOps projects. | As you can see, OSBR is more than just a place to work. It’s a place where we grow and experiment together. At the end of the day, we all want to be a well-rounded and innovative problem solver. If you agree with this philosophy, you’ll fit right in. ## 4. The Tools for Success People would say that the value of an engineers does rely on skill alone. Instead, it lies on adaptability too. A good developer embraces new technologies so that they can find the right tools for the job rather than relying on a single stack. ### 4-1. Core Technologies A strong understanding of fundamental technologies is much needed for building reliable systems. | **Field** | **Core Competencies** | | -------------------- | --------------------------------------------------------- | | Backend Development | API design, database management, server architecture | | Frontend Development | UI frameworks, state management, responsive design | | AI & Data Processing | Machine learning basics, data pipelines, model deployment | | Cloud Computing | Cloud services, containerization, serverless architecture | There's no mandate on a single tech stack right? It's your call to which one fits best for the task. ### 4-2. The Mindset of a Polyglot Engineer The general consensus is that a well-rounded engineer: * Recognises the advantage of multiple languages (Python, JavaScript, Go, Rust, etc.) * Cares about programming paradigms (object-oriented, functional) * Adapts to new languages and frameworks based on project needs Just like this handbook is always evolving, wouldn't you agree that an engineer’s greatest strength is their ability to adapt too? ### 4-3. Collaboration and Version Control Software development is a team effort, and effective collaboration is critical anywhere. For that reason, we must be comfortable working within workflows and using version control systems like Git. ```mermaid --- title: Development Workflow --- graph TB; A[Feature Development] -->|Create Branch| B[Local Branch] B -->|Write & Test Code| C[Code Commit & Push] C -->|Open Pull Request| D[Code Review] D -->|Approved| E[Merge to Main Branch] D -->|Needs Changes| C E -->|Trigger CI/CD| F[Automated Testing & Deployment] F -->|Deployed Successfully| G[Project Updated] ``` After all, you're not alone in pushing changes to technology. You're standing on the backs of those before you and together, the impossible begins to look a little more possible. ## 5. Application Process Our hiring process is transparent and straightforward, so you know what to expect. ```mermaid --- Title: Application Process --- graph TB; A[Submit Application] --> |Job Platforms| B[Initial Screening] A --> |Email Us| B B --> C[Online Interview] C --> D[Technical Assessment] D --> E[Final Interview] E --> F[Offer & Onboarding] %% Rejection paths C --Try Again--> A; D --Try Again--> A; E --Try Again--> A; ``` ### 5-1. How to Apply You can apply through the following channels: 1. Job Platforms We post openings on [Jobstreet](https://my.jobstreet.com/?icmpid=js_global_landing_page), [Hiredly](https://my.hiredly.com/), and our [official website](https://www.osbrjp.com/en/). 2. Direct Email You can email your application to info@osbrjp.com, including: * Your resume (PDF preferred) * A link to your portfolio (GitHub, personal website, etc.) * A short cover letter explaining your interest in OSBR and the role ### 5-2. What to Expect #### Application Submission * Submit your application through any of the available channels. Make sure your resume and portfolio are up to date. #### Initial Screening (1-2 weeks) * A quick introduction to understand your motivations and interests. * You'd be reached via a phone call. #### Online Interview (30-45 mins) * A casual conversation about your background, past projects, and problem-solving approach. * Includes a few personality and culture-fit questions. #### Technical Assessment (Varies) * A take-home challenge or a live coding session. * We'll coordinate a time that works for you and us. * If you don’t pass, we’ll provide feedback, and you can reapply after 3 months. #### Final Interview * Meet the team, discuss expectations, and understand how you'd fit within OSBR. #### Offer & Onboarding * You're a perfect match, welcome aboard! * You’ll receive your offer letter with role details and next steps. ### 5-3. Frequently Asked Questions 1. How long does the entire hiring process take? On average, 3-4 weeks, but this may vary based on the number of applicants. 2. Can I apply for multiple roles? Yes! If you’re interested in multiple positions, mention them in your application. 3. What if I don’t pass the technical assessment? You’re welcome to reapply after 3 months. We encourage you to improve based on the feedback provided. 4. Do you accept remote applications? At the moment, we prioritize on-site positions at OSBR headquarters, but some roles may offer flexibility. --- --- url: /on-boarding.md --- # On-boarding Guide Welcome to OSBR! This guide outlines the on-boarding process for new team members. \[\[TOC]] ## 1. First Day ### 1-1. Company Introduction On the first day, new team members will receive a formal introduction to OSBR. This process includes: * **Welcome meeting**: A 30-minute session with the team lead to welcome the new member * **Vision and strategy presentation**: Overview of OSBR's vision, business models, and strategic direction using the [Strategy Overview](/strategy) document * **Company history discussion**: Insight into OSBR's journey, from its founding to current initiatives * **Q\&A session**: Opportunity for new members to ask questions about the company The HR representative will schedule these sessions and provide access to relevant documentation before the meetings. New members should review the [Strategy Overview](/strategy) document in advance to make the sessions more productive. ### 1-2. Account Preparation / Introduction to Internal Tools On the first day, the IT team will set up necessary accounts for new team members: | Account Type | Setup Process | Required Information | |--------------|---------------|----------------------| | **Google Workspace** | HR sends invitation to company email | Personal email for verification | | **Slack** | Manual invitation after Google setup | Google account | | **GitHub** | Manual invitation to organization | GitHub username or email | After setting up accounts, the IT team will briefly introduce you to our basic tools and how to access them. This short orientation covers just what you need to get started with our daily communication and work systems. ### 1-3. Kitting #### Device Setup * Configure sleep mode to activate within 5 minutes, with mandatory reauthentication after sleep * Install antivirus software on Windows devices * Prohibit keeping files permanently on the desktop * Prohibit displaying text in the browser's bookmark bar * Configure proxy settings for verification and production environment testing ::: warning Notice Development on self-built development servers is prohibited. ::: #### GitHub Email Notification Settings Configure your email notification settings to receive notifications from GitHub. Ensure that you are notified when other developers mention you. #### Container Runtime Environment Setup Make sure you can execute the `docker` and `docker compose` commands on your terminal. Containers will be used for development tasks such as compiling, running applications, package management, and executing tests. ::: info NOTE While Docker Desktop is the standard reference, you can also use other tools like Rancher Desktop. ::: #### Editor Configuration Set up your editor to enable features like auto-completion, navigation, and error checking for the languages used in the project (TypeScript, Go). Also, configure it to automatically format code upon file save. Use Prettier for TypeScript and `go fmt` for Go. #### Language Runtime Environment Setup While container-based development environments are the default, also set up the runtime environment for the languages on your local machine. For Node.js, use tools like `nodebrew` that allow easy version switching. ::: info NOTE Some tools, such as AWS CDK, might require credentials to be passed via environment variables or files when run inside containers. Due to security considerations, a non-container-based approach might be preferred in such cases. ::: #### Enable Screenshots and Screen Recording Throughout the development process, you may need to record operations as images or videos. Set up your system to be ready for this when needed. For Mac, it is recommended to use **Skitch** for screenshots and **QuickTime Player** (`shift + command + 5`) for video recording. #### Subscribe to Japan & Malaysia Holiday Event Calendar Since OSBR has employees from both Japan and Malaysia, it is important to receive notifications when the current or following day is a public holiday in either country. This helps in planning tasks and meetings more effectively. To subscribe to a holiday calendar on macOS: 1. Open the Calendar app. 2. Go to File > New Calendar Subscription. 3. Enter the calendar's web address (like https://www.officeholidays.com/ics/malaysia). 4. And follow the prompts to name the calendar, choose an account, and set update frequency. ::: info NOTE You can use your preferred calendar app such as Google Calendar. ::: ## 2. First Week ### 2-1. Reading the OSBR Handbook During your first week, you should thoroughly review the OSBR Handbook to understand our company philosophy, processes, and expectations. Understanding our development flow and the intention behind our workflow is particularly important. While agile methodologies typically prioritize communication over documentation, we place significant value on documentation. To maintain agility, we focus on recording essential information with less effort in the right places, creating a system where this documentation enhances rather than hinders our agile practices. This balance allows us to preserve knowledge effectively while maintaining the flexibility and responsiveness that agile development requires. ### 2-2. Tutorial During your first week, you'll complete a hands-on tutorial that walks you through our entire development workflow. This tutorial is conducted in a safe environment using the [`osbrjp/tutorial`](https://github.com/osbrjp/tutorial) repository, where you can practice without affecting production systems. The tutorial covers these key activities: 1. Creating an issue with the appropriate template 2. Starting a pull request with detailed specifications 3. Getting a specification review from a team member 4. Making code changes in a properly named branch 5. Conducting a self-review and attaching evidence (screenshots/videos) 6. Requesting an implementation review 7. Experiencing the release process This practical exercise will help you internalize our development practices and understand how we track, implement, review, and deploy changes. Your mentor will guide you through this process and answer any questions you have along the way. ### 2-3. Meet the Team After completing the tutorial, you'll contribute to the [`osbrjp/meet-the-team`](https://github.com/osbrjp/meet-the-team) repository to introduce yourself to your colleagues. This exercise serves two purposes: further practice with our workflow and helping the team get to know you better. The process involves: 1. Creating an issue titled "Introduce \[Your Name]" 2. Working through our standard workflow with a pull request 3. Creating your personal introduction page in the repository 4. Writing a reflective essay on what "Be Nice, Be Kind, Be Strong" means to you Your introduction should follow the provided template and include information about your role, interests, and background. The "Be Nice, Be Kind, Be Strong" essay is an important part of our team culture, encouraging you to think about these values in your own words. This assignment helps integrate you into the team's culture while giving you additional practice with our development workflow in a low-pressure context. ### 2-4. First Handbook Assignment In your first week, you'll make a small but meaningful contribution to the OSBR Handbook itself. While this isn't software code, it's equally important as it's our live documentation that guides the entire team's work. We believe that everyone, regardless of tenure, should be able to contribute to our documentation. While major changes to handbook rules would not be appropriate for someone who just joined, we don't want to restrict editing only to those with longer tenure. Fresh perspectives often notice inconsistencies, unclear explanations, or opportunities for improvement that those familiar with the content might miss. For this assignment: 1. Identify a small area of the handbook where you can make an improvement * This could be fixing a typo, clarifying wording, adding a missing explanation, or suggesting a small enhancement * Your mentor can help you find an appropriate area if needed 2. Use our standard workflow (as practiced in the tutorial) to propose and implement this change * Create an issue describing what you'd like to improve and why * Get feedback on your approach * Make the change through a pull request * Attach appropriate evidence for review This exercise demonstrates our commitment to collective ownership of documentation and gives you the confidence to suggest improvements from day one. Finding ways for new team members to contribute immediately is important to us, even if those contributions start small. ## 3. First Month ### 3-1. Mastering Technical Terminology During your first month, you'll need to familiarize yourself with the technical terminology commonly used at OSBR. Understanding these terms is crucial for effective communication with team members and clients. We've created a comprehensive technical glossary that you should review and reference as needed. The glossary includes formal definitions, common usage contexts, and related concepts for each term. Your mentor will guide you through this learning process and help identify which terms are most relevant to your specific role and projects. As part of this process, you'll be asked to: 1. Review the technical glossary 2. Identify terms you're unfamiliar with 3. Learn and practice using these terms in appropriate contexts 4. Develop insights into how different terms relate to each other and form a cohesive understanding of our technology ecosystem You can access the full technical glossary [here](/technical-glossary). ### 3-2. Practice Project Using Our Workflow After the tutorial, you'll work on a practice project alongside your terminology learning (3-1). This small, self-contained project applies our complete workflow in a realistic setting and typically takes **1-2 weeks**. For this assignment, you'll create multiple issues and pull requests while receiving guidance from your mentor. You'll experience the entire process from planning to implementation to release, with feedback on both technical implementation and process adherence. The project uses actual production technologies and frameworks relevant to your future work, bridging the gap between tutorials and real projects while providing a safe learning environment. ### 3-3. Research Assignment for Your First Real Project Before joining your first real project, you'll research the project's domain and technical requirements. This includes reviewing documentation, studying the technology stack, understanding business requirements, and identifying potential contributions. Your mentor will guide this process and connect you with team members. At month's end, you'll present your findings to the project team, marking your transition to active participation. --- --- url: /development-guide.md --- # Development Guide In this page, you will find the standard development policy and workflow in OSBR. \[\[TOC]] ## 1. Setup Your Environment ### 1-1. Setup Your Machine The following checklist is all mandatory by our security policy: * Use company-provided laptop or company-approved personal device. * Sleep mode activation within 5 minutes, mandatory reauthentication after sleep mode. * Install antivirus software on Windows devices. * Prohibit keeping files permanently on the desktop. * Prohibit displaying project or client names in the browser’s bookmark bar. * Configure proxy settings for verification and production environment testing. * Ask administrator for the proxy settings. ::: warning Notice Development on self-built development servers is prohibited. ::: ### 1-2. Email Notification Settings from GitHub Configure your email notification settings to receive notifications from GitHub. Ensure that you are notified when other developers mention you. ### 1-3. Setting Up the Container Runtime Environment Make sure you can execute the `docker` and `docker compose` commands on your terminal. Containers will be used for development tasks such as compiling, running applications, package management, and executing tests. ::: info NOTE While Docker Desktop is the standard reference, you can also use other tools like Rancher Desktop. ::: ### 1-4. Editor Configuration Set up your editor to enable features like auto-completion, navigation, and error checking for the languages used in the project (TypeScript, Go). Also, configure it to automatically format code upon file save. Use Prettier for TypeScript and `go fmt` for Go. ### 1-5. Setting Up Language Runtime Environments While container-based development environments are the default, also set up the runtime environment for the languages on your local machine. For Node.js, use tools like `nodebrew` that allow easy version switching. ::: info NOTE Some tools, such as AWS CDK, might require credentials to be passed via environment variables or files when run inside containers. Due to security considerations, a non-container-based approach might be preferred in such cases. ::: ### 1-6. Enabling Screenshots and Screen Recording Throughout the development process, you may need to record operations as images or videos. Set up your system to be ready for this when needed. For Mac, it is recommended to use **Skitch** for screenshots and **QuickTime Player** (`shift + command + 5`) for video recording. ### 1-7. Setting Up Application Execution Environments Follow the instructions provided for each project to set up the required execution environment. ### 1-8. Coding Style Guide Follow the [Style Guide](/style-guide) for how we write code: language-agnostic principles plus per-language rules (TypeScript, Go, Python, HTML & CSS, Terraform), each tagged 🌎 industry-standard or 🏠 house-rule. Read it before your first pull request. ### 1-9. Design Guidelines Follow the [Design Guidelines](/design-guidelines) for how the experience behaves: accessibility as the floor, screens that explain themselves, every state designed, and modeless, reachable interaction. They are the counterpart to the Style Guide — that governs how we write code; these govern how the thing we build feels to use. ### 1-10. Database Guidelines Follow the [Database Guidelines](/database-guidelines) when choosing a data store (SQL vs NoSQL) or designing a relational schema, including OSBR's SQL house style. The [Infrastructure Planning Policy](/infra-planning-policy) sets the higher-level infrastructure defaults these build on. ### 1-11. The Quality Gate Follow the [Quality Gate](/quality-gate): the three checks every change clears before it merges — that it is **reliable**, **secure**, and **sustainable**. One engineer, with their AI, holds all three as they build, and the gate holds at `Impl Review` on the board. ### 1-12. AI Usage Guideline Follow the [AI Usage Guideline](/ai-usage-guideline) for how we work with AI: one engineer owning the whole of a piece of work with AI beside them, and the standards — data boundaries, provider resilience, day/night rhythm, policies-as-plugins — that keep AI-assisted work safe, resilient, and honest. ## 2. Workflow Overview ### 2-1. Scrum-Like Agile Development ::: info NOTE We learn from Scrum concepts but do not apply them in their entirety. We adapt them to our needs and constraints. Reference: [Scrum Guide (2020) End Note](https://scrumguides.org/scrum-guide.html#end-note) > While implementing only parts of Scrum is possible, the result is not Scrum. Scrum exists only in its entirety and functions well as a container for other techniques, methodologies, and practices. > ::: Following practices characterize our agile style: #### 1-Week Sprint * Work is broken down into short iterations, typically 1 week. * To ensure continuous delivery of value and frequent opportunities for feedback. * CI/CD pipelines have to be set up and automated first. #### Brief Issues, Contextual Pull Requests * **Issues** should be briefly described to help the team: * Create small, manageable tasks that fit within a 1-week sprint. * Encourage the creation of more issues to track all identifiable tasks at any given moment. * Motivate project leaders to take ownership of issue creation instead of delegating it to team members. * Clarify whether details should be documented in an issue or a pull request, avoiding confusion. * **Pull Requests** should include detailed context to: * Ensure reviewers have all the necessary information without requiring additional clarification from the author. * Integrate seamlessly with tools like GitHub Copilot code review. * Serve as lightweight [ADR](https://adr.github.io/)s by preserving context and making it easier to refer back to decisions in the future. #### Weekly Planning * **Retrospective Session**: * We hold a retrospective to share what went well, what could be improved, and challenges or blockers that hindered progress. * **Set Iteration Goals**: * The team collaboratively defines clear, achievable goals for the sprint, ensuring alignment with overall issues on the project board. * Tasks are selected and assigned to team members based on their capacity and expertise, prioritizing high-impact work that fits within the sprint timeline. #### Visual Evidence Policy * Screenshots and videos must be used to illustrate both issues and pull requests. For pull requests, it is mandatory to provide these as evidence. * This policy is not intended to question developers' integrity but to protect them from potential conflicts within the project. * During retrospective sessions, these visual artifacts are reviewed as part of the sprint demo. ### 2-2. GitHub Configuration Our activities are primarily centered around GitHub rather than other tools. This means our GitHub configuration provides an overview of our development workflow. Following configurations are applied to each repository from the standard template repository. #### Issue Templates Choose one of the following issue types when creating a new issue. | No. | Name | Description | | --- | ---- | ----------- | | 1 | `Addition` | A format for changes made to introduce new code, features, or functionality that did not exist before. | | 2 | `Modification` | A change made to existing code to alter its behavior or add new functionality. | | 3 | `Refactoring` | A change made to existing code to improve its structure, readability, or maintainability without altering its behavior. | | 4 | `Fix` | A change made to correct an error, bug, or unintended behavior in existing code. | | 5 | `Epic` | Group and organize related issues under a single high-level overview of a larger goal. | | 6 | `Idea` | Capture potential features, improvements, or concepts for future consideration. | #### Labels Use following labels to categorize issues. Note these are not for pull requests. | No. | Name | Description | | --- | ---- | ----------- | | 1 | `🧩 Domain Modeling` | Domain model development. | | 2 | `🌐 Server Side` | Server side development. | | 3 | `🖥️ Client Side` | Client side development. | | 4 | `🚑 DB Data Migration` | Executing sql to modify data manually. | | 5 | `🛢️ DB Schema Migration` | Adding another DB schema migration file. | | 6 | `🔄 CI/CD` | Configuring GitHub Actions. | | 7 | `📝 Documentation` | Adding another markdown file or writing more comments. | | 8 | `☁️ IaC` | Cloud infra orchestration by code. | | 9 | `🔧 Ops` | Run one-shot batch program etc. | | 10 | `🔒 Security` | Fixing vulnerabilities or improving security. | #### GitHub Actions The following GitHub Actions are pre-configured in each repository. | No. | Name | Description | | --- | ---- | ----------- | | 1 | `start-pull-request` | Create a pull request by assigning a developer to the issue. | | 2 | `prepare-release` | Prepare a release pull request merging main to release. | | 3 | `run-tests` | Skeleton action which is supposed to run tests. | | 4 | `release` | Skeleton action which is supposed to deploy and publish release note. | #### Status This field belongs to our standard project board. | No | Status | Description | |----|---------------|---------------------------------------------------------------------------| | 1 | Icebox | Not yet prioritized to be worked on. | | 2 | Todo | Ready to be worked on specification. | | 3 | Spec Review | On a specification review before being 'In Progress'. Can skip if enough confident. | | 4 | In Progress | Currently being worked on implementation. | | 5 | Impl Review | On implementation review before being merged: by declaring this status the engineer takes on running the AI review from their own agent, then a human interprets its findings and owns the merge (see [Code Review](/code-review)). | | 6 | Shipping | Merged to 'main' and ready to be shipped. | | 7 | Done | Shipped and verified on the production environment; the issue is closed. | The following is a flowchart of the project status. ##### Flowchart of Status ```mermaid flowchart TD START[Register issue] --> A1[Prioritize on the board] subgraph Todo A1 --> A2[Assign a developer] end subgraph Icebox A1 --> B1[Store until prioritized] B1 --> A2 end subgraph Spec Review A2 --> C1[Write spec on PR] C1 --> C2[Review spec] end subgraph In Progress C2 --> D1[Write code on PR] A2 --> D1 D1 --> D2[Self review] D2 --> D3[Attach evidences] D3 --> D4[Request review] end subgraph Impl Review D4 --> E1[Review code] E1 --Request changes--> D1 E1 --> E3[Approve] end subgraph Shipping E3 --Merge--> F1[Wait for release] F1 --> F2[Release] F2 --> F3[Verify on production] end subgraph Done F3 --> END[Close issue] end ``` #### Priority Priority is used to determine the order of tasks to be worked on. Relatively set and updated by weekly planning. | No | Priority | Description | |----|---------------|---------------------------------------------------------------------------| | 1 | High | High priority, must be done as soon as possible. | | 2 | Medium-High | High priority, but can be done after 'High' priority tasks. | | 3 | Medium | Medium priority, prioritized neither high nor low. | | 4 | Medium-Low | Low priority, but can be done before 'Low' priority tasks. | | 5 | Low | Low priority, can be done after 'Medium-Low' priority tasks. | #### Effort Person days are used to estimate the number of days needed to complete a task. When this has 1 worker day, it means that it can be done in a day by a single person. Minimum person days are 0.25. #### Difficulty Difficulty estimates the complexity of a task, which may arise from unclear specifications or insufficient information, as well as requiring advanced knowledge or expertise. #### Sprint Sprint is a period of time during which specific work has to be completed and made ready for review. It is usually 1 week long. #### Repositories Are Not a Support Channel The issue tracker is the **engineering backlog** — reproducible defects, planned features, and technical debt the team owns and burns down on engineering time. It is not a helpdesk. Support requests — how-to questions, account problems, billing, "is this broken for me?" — run on a different clock and a different audience, and mixing the two buries real defects under noise while answering users on a cadence never designed for them. So before any product goes live it has a **dedicated, published support channel**, and the resolution path for a support request stays entirely inside it. When a request lands as an issue anyway, we **thank** the person, **redirect** them to the support channel with its URL, and **close** the issue — never keep it open under a standing `support` label. The only bridge from support into the tracker runs one way: when a support conversation surfaces a genuine defect, its owner opens a fresh, reproduced, engineer-written issue, and the user stays updated in the support channel. * We **MUST** give every product a nominated, published support channel before it goes live, and resolve support requests there, never through the issue tracker. * We **MUST** handle a support request that arrives as an issue by thank → redirect → close, rather than parking it under a support label. * We **SHOULD** re-file genuine engineering work found via support as a fresh, deduplicated, engineer-written issue — not a forwarded user thread. ### 2-3. Weekly Planning All developers participate in the weekly planning meeting to discuss the progress of the project and plan the next week's work. Following is the typical agenda for the weekly planning meeting. #### Update the project board * Make sure all issues have correct `Labels`, `Priority`, `Effort`, and `Difficulty`. * Check all issues in the previous sprint are closed and "Done" for status. * Carry over issues that are not completed to the next current sprint. #### Review the previous sprint's achievements and challenges * Watch the demo movies of the completed pull requests at the previous sprint. * Highlight completed tasks and their impact on the project. * Identify any blockers or unresolved issues and discuss their root causes. * Share lessons learned to improve future sprints. #### Share individual progress updates * Each team member provides a brief update on their tasks, progress, and any obstacles they are facing. * Encourage questions and collaboration to address blockers or dependencies. #### Align on priorities for the current sprint * Confirm the scope of the sprint based on the carried-over issues and new priorities. * Assign tasks to team members, ensuring alignment with their capacity and expertise. * Discuss any adjustments to the project timeline if necessary. #### Plan for the next steps * Set deadlines for critical issues. * Identify areas where team members may need additional support, such as training or resources. * Schedule a follow-up session to review mid-sprint progress. #### Close the meeting * Summarize key takeaways and action items. * Encourage feedback on the meeting's structure or areas for improvement. * End with a positive note to motivate the team for the upcoming sprint! ### 2-4. Planning & Shaping Before a piece of work reaches the board as something we can build, it has to be shaped — turned from a customer's initiative into a committed, understood slice with a number against it and the riskiest part already tested. This is the pre-work phase, and it maps to the early board stages: `Todo`, where a request lands, and `Spec Review`, where we agree it is worth doing and know enough to do it. A week-long sprint gives us little room to discover halfway through that we were solving the wrong problem, so we spend the front of the effort making sure we are not. **We research the real need before we take a request at face value.** A stated request is a symptom and a hypothesis — evidence of a deeper business need, not the need itself. So we study the customer's world first: how their industry makes money, what people actually do all day versus the tidy process on the org chart, and the workarounds and shadow spreadsheets they have built to survive the current one. We trace each stated request down to the job beneath it — the progress the customer is trying to make, independent of any solution — and we validate that job against what we found. Serving the customer well sometimes means telling them, early and with evidence, that the thing they asked for is not the thing their business needs. That honesty is service, not cleverness at their expense. **We prove the risky part with something that actually runs.** Where an idea carries real uncertainty — whether it will pay off, whether it is what the customer needs, whether people will use it, whether we can even build it — we do not find out by building the whole thing and hoping. We find out cheaply first, with the smallest experiment that answers the question: a spike for a technical unknown, a thin walking skeleton for an end-to-end one, a proof-of-concept for a doubt about value. The experiment is time-boxed and carries a written question and a written "what result changes our plan." Its value is the lesson, not the code — a spike that fails in three days has saved a three-month bet, and that is a success. Experiment code lives in a clearly marked disposable space (a `lab/` or `spike/` area, a `spike:` comment) and is never quietly promoted into production; if the idea is proven, we budget the real build. **We size it honestly, and we judge it by the customer's return.** An estimate is a communication that serves a decision, not a promise squeezed out of us, so every estimate carries a visible breakdown, states plainly what it includes and excludes, and is expressed as a range rather than a single figure that hides how little we yet know. Because agents change task cost sharply but unevenly, an estimate says which world it assumes — scaffolded ground with clear specs and tests, or unprepared ground where that speed-up largely evaporates. Above the cost sits the prior question: for this customer's business, does the return justify the spend, and how sure are we? We rank proposals by their return to the customer, not by how large an order they would be for us; we state the expected effect and how certain we are of it; and we phase large spend into increments the customer can verify before funding the next, attacking the riskiest, highest-value part first. The agreed estimate and the accepted case — range, breakdown, assumptions, increment plan — land in the meeting record, so that when an assumption breaks, re-quoting is fair rather than a fight over memory. **We win and start work by demonstrated capability, not by reciting the past.** When a customer needs to believe we can do the work, we reach for the real thing at hand — a working proof-of-concept against their actual problem, the concrete reasoning behind a design decision, the running service they can click and try to break — before we reach for a list of past projects. A track record answers "were they any good before?"; a demonstration answers "are they solving *this* problem, right now?", and only the second keeps our motivation honestly tied to the customer's value. When we publish case studies to build reputation, we get consent first and keep the detail coarse — the shape of a solution, never the versions, endpoints, and topology an attacker probing the customer's systems would need. **We share one language across customer, code, and team.** The terms we harvest from the customer's world become the project's ubiquitous language — one authoritative word per concept, agreed with the domain experts and mirrored everywhere the concept appears. We search the existing terms before coining a new one, treat a second synonym for an existing idea as a defect rather than a style choice, and flag contradictions (two words for one thing, one word for two) as findings that usually mark a real boundary. When a concept is renamed, the rename is atomic — code, schema, tests, logs, and docs in the same change — so the old word leaves no landmine for the next reader, human or AI. * We **MUST** research the customer's industry, real workflow, and pain before treating a request as a specification, and trace every request down to the job it is trying to satisfy. * We **MUST**, where real uncertainty exists, reduce it with the smallest time-boxed experiment that answers a written question — and keep that experiment disposable and out of production until the real build is budgeted. * We **MUST** give every estimate a visible breakdown, explicit scope in/out, a range not a single figure, and a stated assumption about scaffolded versus unprepared ground. * We **MUST** rank proposals by return to the customer rather than order size to us, state the expected effect and its certainty, and phase large spend into increments the customer can verify before funding the next. * We **MUST** record the agreed estimate and accepted case, with their assumptions, in the meeting record. * We **SHOULD** demonstrate capability with a runnable proof-of-concept, design reasoning, or the live service before citing past work — and publish case studies only with consent and with detail kept coarse. * We **SHOULD** capture the field's own terms verbatim as the project's ubiquitous language, one word per concept, and hold that language consistent across the customer, the code, and the team. Each part of shaping has a full standard behind it: [Market Research](/market-research), [Requirements Modeling](/requirements-modeling), [Verify Before Building](/verify-before-building), [Cost Estimation](/cost-estimation), [IT Investment Evaluation](/it-investment-evaluation), [Legal Compliance](/legal-compliance), [Domain Terminology](/domain-terminology), and [Capability over Track Record](/capability-over-track-record). ## 3. Tutorial ::: info Notice The `osbrjp/tutorial` is a private repository. ::: If you are a new developer, start by following the tutorial below on the `osbrjp/tutorial` repository. `osbrjp/tutorial` is a safe repository for learning and getting used to our standard workflow, so feel free to experiment and ask questions. ### 3-1. Create your first issue #### Choose issue template Select the issue template from Addition, Modification, Refactoring, or Fix. ![Choosing issue template](/static/development-guide/1.jpg) #### Fill out the form Complete all the required fields in the issue form, ensuring the details are clear and concise. ![Filling out the form](/static/development-guide/2.jpg) #### Fill extra fields Provide any additional information required to align the issue with the project board. Take ownership of the issue by assigning it to yourself. ![Filling extra fields](/static/development-guide/3.jpg) *** ### 3-2. Working on the pull request #### Fill "Specification / Test Plan" on the pull request Describe the purpose of your changes and how they will be tested in the "Specification / Test Plan" section of the pull request. ![Filling specification](/static/development-guide/4.jpg) #### Ask someone to review your specification Set the issue status to `Spec Review`. Mention the reviewer on the pull request. The reviewer will provide a comment to proceed to the next step. ![Asking review](/static/development-guide/5.jpg) #### Clone the repository Set the issue status to `In Progress`. Clone the repository to your local machine and check out the branch automatically created alongside the pull request. The branch name follows the format i\[issue\_no]-\[DATE]-\[HHMM]. ```bash $ git clone git@github.com:osbrjp/tutorial.git $ cd tutorial $ git checkout i1-20250210-1307 # example ``` #### Edit and push Edit README.md. Just put/remove another black line is enough for this tutorial. Put some commit messages like "Fix README.md" to push the changes. #### Self review and attach evidences Return to the pull request and review your changes in the Files changed tab. Provide additional context to explain the purpose of your changes and add any necessary review comments. If everything looks good, submit your review with the "Approve" option to complete the "Self Review" process. After that, record a video on your machine as evidence of the changes and attach it to the pull request description. ![Self reviewing](/static/development-guide/6.jpg) Tips: `cmd + shift + 5` for taking video on your computer, finish it up with `cmd + control + esc`. #### Request review Set the issue status to `Impl Review`. Check the "Self Review" and "Evidence" checkboxes in the pull request description. Set the "Reviewers" field to the reviewer's name, and add a comment mentioning the reviewer with a nice message, and include a note about the desired review deadline if necessary. #### Merge the pull request The reviewer merges the pull request into the main branch at the same time they approve it. Afterward, the issue status changes to `Shipping`. *** ### 3-3. Release #### Check the release pull request The release pull request is created automatically when the pull request is merged into `main`. Check the release branch to ensure the changes are included. ![Checking release pull request](/static/development-guide/6.jpg) #### Review and merge the release pull request Approve the release pull request and merge it into the release branch. In a real development process, this operation is carried out by the team. #### Verify the release In a real development process, the release is verified by the team on the production environment. --- --- url: /style-guide.md --- # Coding Style Guide Language-agnostic coding style guide for OSBR repositories. Per-language guides: * [TypeScript Style Guide](/style-guide-typescript) * [Golang Style Guide](/style-guide-golang) * [Python Style Guide](/style-guide-python) * [HTML & CSS Style Guide](/style-guide-html-css) * [Terraform Style Guide](/style-guide-terraform) ## How to read this guide * **Requirement levels** follow RFC 2119. **MUST** / **MUST NOT** are absolute. **SHOULD** / **SHOULD NOT** state a strong default that MAY be overridden only with a documented reason. **MAY** marks a choice left to the author. * **Rule tags.** Every rule carries exactly one tag. 🌎 (**Industry standard**) is backed by an official or widely adopted source. 🏠 (**OSBR house rule**) is deliberately stricter than, or divergent from, mainstream practice; every 🏠 section ends with a *Rationale:* line naming the baseline it diverges from. Sources are listed under References. * **Worked examples.** The per-language pages state a rule, then show it with a ❌ counter-example followed by the ✅ form to write instead. * **Defined terms.** Words in **bold links** are defined in the [Technical Glossary](/technical-glossary). \[\[TOC]] ## 1. Correctness by Construction — Zero Runtime Errors 🏠 Every rule below serves one goal: eliminate avoidable runtime errors and make the unavoidable ones explicit. * Avoidable errors MUST be moved to compile time. Illegal states MUST be made unrepresentable through the type system (strict types, total types, discriminated unions, [**Brand Type**](/technical-glossary#brand-type)s) rather than guarded at runtime. * Code MUST NOT fail at runtime for a condition the types could have rejected: no `any` escape hatch, no unchecked `null` / `undefined`, no unvalidated external input reaching the pure core. * Unavoidable failures (IO, network, DB, external input) MUST be handled explicitly as values ([**Result (Either)**](/technical-glossary#result-either) / [**Option (Maybe)**](/technical-glossary#option-maybe), §5) and MUST NOT be left to throw uncaught. *Rationale: literal zero runtime errors is impossible — external systems fail. The target is to make every avoidable error a compile error and every unavoidable one an explicit, handled value. The strict-typing, total-type, and error-handling rules below are the mechanism.* ## 2. Functional Style 🏠 * Project code MUST NOT use classes. Prefer functions, plain data, and composition. * Project code MUST NOT mutate data in place. * Functions MUST be free of [**Side Effect**](/technical-glossary#side-effect)s; IO MUST be pushed to the boundary (§3-5, §5). * Dependencies SHOULD be inverted by passing behavior as a [**Higher Order Function**](/technical-glossary#higher-order-function), not by hard-wiring a concretion. * Classes and mutation MAY be used inside external libraries, or at framework boundaries that require them (e.g. React error boundaries, ORM entities). *Rationale: stricter than mainstream, which permits classes and limits immutability to the binding level.* ## 3. Design Principles & Separation of Responsibilities These rules apply the handbook's [**Clean Architecture**](/technical-glossary#clean-architecture), [**DiP**](/technical-glossary#dip-dependency-inversion-principle), [**DI**](/technical-glossary#di-dependency-injection), and [**Ubiquitous Language**](/technical-glossary#ubiquitous-language) commitments. SOLID is stated paradigm-neutrally; Robert C. Martin restates it without reference to classes. ### 3-1. Single Responsibility 🌎 * A module MUST have one reason to change — one *actor* (person or business function). Group code that changes for the same reason; separate code that changes for different reasons. * The rule applies to functions and modules, not only classes. *Rationale: SRP is a cohesion rule, not "do one thing." The function-cohesion reading is the functional community's.* ### 3-2. Separation of Concerns 🌎 * Each concern — domain rules, application orchestration, IO, presentation — MUST live in its own module. *Rationale: the term originates with Dijkstra (EWD447, 1974).* ### 3-3. The Dependency Rule 🌎 * Source-code dependencies MUST point inward only. An inner layer MUST NOT know anything about an outer layer. * **Domain (Entities)** — enterprise-wide business rules. MUST be pure: no [**Side Effect**](/technical-glossary#side-effect), no IO; built from [**Value Object**](/technical-glossary#value-object)s named in the [**Ubiquitous Language**](/technical-glossary#ubiquitous-language). * **Application (Use Cases)** — application-specific rules orchestrating the domain. * **Infrastructure** — UI, DB, frameworks; outermost and replaceable. * The Domain MUST NOT import from Application or Infrastructure — Domain-Driven Design concentrates domain-model code in one isolated layer (Evans). *Rationale: an entity "can be a set of data structures and functions" (Martin), so a pure functional domain is in scope; the layer count is an example, not a mandate.* ### 3-4. Dependency Inversion 🌎 *(functional mapping is community practice)* * High-level modules MUST depend on abstractions, not concretions ([**DiP**](/technical-glossary#dip-dependency-inversion-principle)). * In no-classes code, dependencies MUST be inverted by passing functions inward: the inner layer declares the signature it needs; an outer layer supplies it ([**Higher Order Function**](/technical-glossary#higher-order-function) / [**DI**](/technical-glossary#di-dependency-injection)). * A port with several operations SHOULD be a record of functions, not a multi-method interface. *Rationale: the function mapping is Seemann's synthesis, not Martin's wording.* ### 3-5. Ports & Adapters 🌎 * The pure core MUST define *ports*; technology-specific IO MUST live in *adapters* at the boundary. Inner code MUST NOT leak to the outside. *Rationale: Hexagonal Architecture (Cockburn); the structural form of §5's boundary rule — Bernhardt's "functional core, imperative shell."* ### 3-6. Responsibility Segregation 🌎 * A function SHOULD either perform an effect (command) or return a value (query), not both (Command–Query Separation, Meyer). * CQRS (separate read and write models) MUST NOT be a default. It MAY be used only where a specific bounded context requires it. *Rationale: Fowler — "for most systems CQRS adds risky complexity"; using it by default is [**Over Engineering**](/technical-glossary#over-engineering) (§4).* ## 4. Simplicity First — KISS / YAGNI 🌎 * Abstractions MUST NOT be added before they are needed: no interface with a single implementation, no factory for a single product, no config for a value that never changes. * Deletion SHOULD be preferred over addition, and boring over clever. * The standard library, then an already-installed dependency, MUST be preferred before writing custom code or adding a new dependency. * Non-obvious design decisions MUST be recorded as an [**ADR**](/technical-glossary#adr-architecture-decision-record), not encoded in speculative abstraction. ## 5. Error Handling * Failures MUST be returned as values ([**Result (Either)**](/technical-glossary#result-either)), not thrown. Absence MUST be represented with [**Option (Maybe)**](/technical-glossary#option-maybe), not `null`. * Programmer bugs, broken invariants, and impossible states MUST throw or panic: crash, log, no recovery. * Expected failures (bad input, not-found, IO failure) MUST return a `Result`. Test: *"would retrying succeed?"* — yes → `Result`; no → throw. * `try`/`catch` MUST be confined to the boundary (IO / network / DB) and convert throws into a `Result` there. The pure core MUST stay free of `try`/`catch`. One top-level catch-all SHOULD remain as a safety net. * Errors MUST be collected in an array (`E[]`); a single error is length 1. * Context MUST be appended to the flat error array (chain), not nested. *Rationale: Go 🌎 — errors-as-values is mandated by Go. TypeScript & Python 🏠 — Google's guides and PEP 8 use exceptions; the `Result` policy is an OSBR choice.* ## 6. Formatting & Tooling 🌎 * Editors MUST format on save. * Formatting MUST be enforced by tooling (gofmt, Prettier / gts, Black / Ruff); see each language page. * Repositories MUST use the shared config templates ([`templates/`](https://github.com/osbrjp/handbook/tree/main/templates)): the language-agnostic `.editorconfig` plus the per-language formatter config. The same files ship in `osbrjp/standard-repository`, so a repo scaffolded from that template already carries them. * [**TDD**](/technical-glossary#tdd-test-driven-development) SHOULD be used; the pure core (§3-5) is testable without mocks. ## References * Robert C. Martin, The Single Responsibility Principle — * Robert C. Martin, SOLID Relevance — * Robert C. Martin, The Clean Architecture — * Alistair Cockburn, Hexagonal Architecture — * Edsger W. Dijkstra, EWD447, On the role of scientific thought — * Eric Evans, Domain-Driven Design — * Gary Bernhardt, Boundaries — * Martin Fowler, CQRS — * Martin Fowler, CommandQuerySeparation — * Mark Seemann, SOLID: the next step is Functional — * Google TypeScript Style Guide — * Go Code Review Comments — * Uber Go Style Guide — * Effective Go — * PEP 8 — * Google Python Style Guide — --- --- url: /style-guide-typescript.md --- # TypeScript Style Guide Per-language style guide for TypeScript. Shared rules: the [Coding Style Guide](/style-guide). Requirement levels follow RFC 2119; tags 🌎 / 🏠 are defined there. \[\[TOC]] ## 1. Formatting 🌎 * Code MUST be formatted with Prettier. Editors MUST format on save. *Note: Prettier is used by Google's `gts`. [Biome](https://biomejs.dev/) is a rising 2026 alternative; Prettier remains the default.* ## 2. Type Safety 🌎 * `tsconfig` MUST enable `strict`. Implicit `any` MUST NOT be used. * `type` aliases and discriminated unions SHOULD be preferred over `class` hierarchies (§5). * A [**Brand Type**](/technical-glossary#brand-type) MUST be used to give [**Nominal Typing**](/technical-glossary#nominal-typing) where two structurally identical types must not be interchangeable (e.g. `UserId` vs `OrderId`). ## 3. Immutability 🏠 * Variables MUST be declared `const`. `let` MAY be used only where reassignment is required. `var` MUST NOT be used. * Data types MUST be deeply `readonly` (`readonly` members, `ReadonlyArray`, `Readonly`, `as const` for literals). A mutable type MUST be used only where in-place mutation is intended. * Function parameters MUST NOT be mutated; spread SHOULD be preferred over `Object.assign`. * Immutability MUST be enforced by [`eslint-plugin-functional`](https://github.com/eslint-functional/eslint-plugin-functional). *Rationale: `const` prevents rebinding only, not content mutation. Deep `readonly` is stricter than Google/Airbnb.* ## 4. Total Types 🏠 * Project code MUST NOT use `undefined` in its own types. * Domain and application types MUST NOT signal absence with `undefined` or a bare `null` — use [**Option (Maybe)**](/technical-glossary#option-maybe). Optional properties (`x?: T`) and `T | undefined` unions MUST NOT mean "maybe absent." * Functions MUST return `T` or `Option`, never `T | undefined`. * `null` MAY appear at the boundary (DB rows, JSON, the DOM, `Map.get`, third-party APIs). It MUST be converted to `Option` in the adapter before entering the pure core. * `tsconfig` MUST enable `strictNullChecks` and `noUncheckedIndexedAccess`. ❌ "Maybe absent" leaks out of the function as `undefined`: ```ts function findUser(id: UserId): User | undefined { return users.get(id); // callers must remember to check } ``` ✅ Absence is explicit in the type: ```ts import { type Option, some, none } from "./option"; function findUser(id: UserId): Option { const user = users.get(id); return user === undefined ? none : some(user); } ``` *Rationale: `null` is a defined value and the DB-native representation of absence; `undefined` is accidental "not set." Divergent from Google, which treats `undefined` as normal; not a language-wide ban.* ## 5. Classes 🏠 * `class` MUST NOT be used in project code; prefer functions, plain data, and closures. * Classes MAY be used where a framework or library requires them. ❌ State and behavior bundled in a class: ```ts class Rectangle { constructor(private readonly w: number, private readonly h: number) {} area(): number { return this.w * this.h; } } ``` ✅ Plain data plus a function: ```ts type Rectangle = { readonly w: number; readonly h: number }; const area = (r: Rectangle): number => r.w * r.h; ``` *Rationale: divergent from mainstream — classes are first-class in TypeScript; Google discourages only static-only namespacing classes.* ## 6. Error Handling 🏠 * Failures MUST be modeled as a [**Result (Either)**](/technical-glossary#result-either): ```ts type Result = | { ok: true; value: T } | { ok: false; error: E[] }; ``` * The `Result` union SHOULD be hand-rolled (KISS / YAGNI). [`neverthrow`](https://github.com/supermacro/neverthrow) MAY be adopted only where its combinators (`map` / `andThen` / `mapErr` / `ResultAsync`) are needed at scale. * IO / `fetch` / DB calls MUST be wrapped at the boundary and return a `Result`; the pure core MUST stay free of `try`/`catch`. ❌ Failure is thrown, and a caller can ignore it: ```ts async function loadUser(id: UserId): Promise { const res = await fetch(`/users/${id}`); if (!res.ok) throw new Error("request failed"); return res.json(); } ``` ✅ Failure is returned as a `Result` the caller must handle: ```ts async function loadUser(id: UserId): Promise> { try { const res = await fetch(`/users/${id}`); if (!res.ok) return { ok: false, error: ["request failed"] }; return { ok: true, value: await res.json() }; } catch { return { ok: false, error: ["network error"] }; } } ``` *Rationale: divergent from Google's TS guide, which prefers throwing exceptions.* ## References * Google TypeScript Style Guide — * TypeScript Handbook, Classes — * `tsconfig` `strict` reference — * Airbnb JavaScript Style Guide — * Google `gts` — * `eslint-plugin-functional` — * Biome — --- --- url: /style-guide-golang.md --- # Golang Style Guide Per-language style guide for Go. Shared rules: the [Coding Style Guide](/style-guide). Requirement levels follow RFC 2119; tags 🌎 / 🏠 are defined there. \[\[TOC]] ## 1. Formatting 🌎 * Code MUST be formatted with `gofmt`. A `gofmt` diff MUST block review. * Code MUST follow [Effective Go](https://go.dev/doc/effective_go) and [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments). ## 2. Error Handling 🌎 * Functions MUST return `error`; callers MUST handle it at the call site: ```go v, err := doThing() if err != nil { return fmt.Errorf("doThing: %w", err) } ``` * Errors MUST be wrapped with `%w` to add context. Errors MUST NOT be discarded with `_`. * `panic` MUST NOT be used for normal error handling. * `panic` MAY be used for unrecoverable bugs or program init, but MUST NOT cross a package boundary — convert it to an `error` first. ❌ `panic` used for an expected failure crashes the caller: ```go func mustLoad(id string) User { u, err := db.Load(id) if err != nil { panic(err) } return u } ``` ✅ The failure is returned as an `error` the caller must handle: ```go func load(id string) (User, error) { u, err := db.Load(id) if err != nil { return User{}, fmt.Errorf("load %s: %w", id, err) } return u, nil } ``` *Rationale: errors-as-values is mandated by Go (Go Code Review Comments, Uber, Effective Go). Go's `error` return is the idiomatic [**Result (Either)**](/technical-glossary#result-either).* ## 3. Mutation 🌎 *(scoped)* * Mutable global state MUST be avoided; use dependency injection. * Slices and maps MUST be copied at API boundaries to avoid aliasing. *Note: Go idiom permits local mutation; the constraint is on globals and boundary aliasing.* ## 4. Interfaces 🌎 * Interfaces SHOULD be small and defined by the consumer. An interface with a single implementation MUST NOT be exported. *Note: Go idiom is "accept interfaces, return structs" with consumer-defined interfaces (Go Code Review Comments, Effective Go).* ## References * Go Code Review Comments — * Effective Go — * Go: Defer, Panic, and Recover — * Go Wiki: PanicAndRecover — * Uber Go Style Guide — --- --- url: /style-guide-python.md --- # Python Style Guide Per-language style guide for Python. Shared rules: the [Coding Style Guide](/style-guide). Requirement levels follow RFC 2119; tags 🌎 / 🏠 are defined there. \[\[TOC]] ## 1. Formatting 🌎 * Code MUST be formatted and linted with [Ruff](https://docs.astral.sh/ruff/) (Black-compatible). Editors MUST format on save. * Code MUST follow [PEP 8](https://peps.python.org/pep-0008/). *Note: Ruff replaces Flake8 + Black + isort in one tool; a project MAY run Black directly instead.* ## 2. Type Hints 🏠 * Function signatures MUST carry type hints. * Type hints MUST be enforced by [mypy](https://mypy.readthedocs.io/) or pyright in CI. *Rationale: stricter than PEP 484, which says hints will never be mandatory; the language does not check them at runtime.* ## 3. Functional Style 🏠 * Plain functions, frozen `dataclasses` (a [**Value Object**](/technical-glossary#value-object)), and immutable data MUST be preferred over stateful classes. * The pure core MUST be free of [**Side Effect**](/technical-glossary#side-effect)s. * Comprehensions and generator expressions SHOULD be preferred over manual accumulation loops where they stay readable. *Rationale: stricter than mainstream Python, which treats classes and object-oriented style as the default structuring tool.* ## 4. Error Handling 🏠 * Expected failures SHOULD be modeled as return values where it aids clarity. * `raise` MUST be reserved for programmer bugs and broken invariants; exceptions MUST be caught at the boundary. * Bare `except:` MUST NOT be used; catch specific exceptions and chain with `raise X from Y` (PEP 8). ❌ An expected "not found" flows through an exception, caught blindly: ```python def find_user(users: dict[str, User], uid: str) -> User: try: return users[uid] except: # bare except hides real bugs return None # absence smuggled back through the type ``` ✅ Expected absence is a return value; `raise` is kept for real bugs: ```python def find_user(users: dict[str, User], uid: str) -> User | None: return users.get(uid) ``` *Rationale: divergent from Python's EAFP idiom, where exceptions are the standard error-handling mechanism.* ## References * PEP 8 — * PEP 484 (Type Hints) — * Google Python Style Guide — * Python tutorial, Errors and Exceptions — * Ruff — --- --- url: /style-guide-html-css.md --- # HTML & CSS Style Guide Per-language style guide for HTML and CSS. Shared rules: the [Coding Style Guide](/style-guide). Requirement levels follow RFC 2119; tags 🌎 / 🏠 are defined there. \[\[TOC]] ## 1. Formatting 🌎 * HTML and CSS MUST be formatted with Prettier. Editors MUST format on save. * Prettier's shared [`.prettierrc.json`](https://github.com/osbrjp/handbook/tree/main/templates) applies unchanged: Prettier formats `.html`, `.css`, `.scss`, and `.less` out of the box, so no extra config is needed. *Note: Prettier is the single formatter across TypeScript, Markdown, HTML, and CSS. Stylelint MAY be added for lint rules Prettier does not cover (e.g. declaration order, disallowed units), but MUST NOT re-implement formatting.* *Note: Prettier is mandated because its HTML formatter is the only stable one. [Biome](https://biomejs.dev/) (CSS stable, HTML still experimental) and [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) (beta, ~30× faster) are Prettier-compatible alternatives to revisit once their HTML support stabilizes. A toolchain-wide switch MUST be an [**ADR**](/technical-glossary#adr-architecture-decision-record), not a per-page choice.* ## 2. Semantic HTML 🌎 * Elements MUST be chosen for meaning, not appearance. Landmarks (`
`, `